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1 . Introduction 

SUN is the Stanford University Network. This is an on-going effort of several groups within Stanford 
University to provide a local computer network for Stanford University [2), based on inexpensive but high 
performance workstations [3]. The network currently connects several time-sharing systems [7] in the 
Computer Science and Electrical Engineering Departments, with plans to extend the network to the rest of 
the campus [16]. The processor architecture in the workstation is the Motorola MC68000. The workstation 
uses the Intel Multibus^, which is proposed IEEE standard 796, so many other common peripheral interfaces 
are comercially available. "Workstation" is used instead of "personal computer" or "tenninal" to emphasize 
the flexibility of the design. 
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Figure 1-1: Major SUN Workstation Components 

There are currently several operating systems being developed for the SUN workstation. Perseus\l)\ is a 
distributed operating system based on messages and links [4] that has been evolving for several years. It is 
written in Pascal* [8], a version of Pascal for systems programming. In the mean time, there are several 
attempts to bring up Unix in various stages. Vaughan Pratt has written his own stream-based operating 
system (sec Chapter 7). Another operating system is being developed to be used in a multi-processor 
configuration. 



Multibus is a trademark of Intel Corporation 
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1.1. Intended Audience 

This manual is intended for people who want to write programs for the SUN workstation. Eventually this 
should be called the "Hacker's Manual," with a separate manual sparing casual users of the unnecessary 
implementation details. The emphasis is on getting consistent up-to-date information, rather tiian a pretty 
manual. Suggestions, additions, editors, and proofreaders arc welcome. Many of tlic tools described here are 
preliminary or interim in nature. Since everything changes so fast, you can incrementally generate any of the 
chapters of this manual. 

The source for this document is stored in [Shasta]/usr/sun/doc. Each chapter exists as a press file, 
which can be printed with the cz command. 

cd /usr/sun/doc 

cz <c/)apter>. press 

There is a makefile in that directory, so a command of the form 

cd /usr/sun/doc 
make <cftapter>,pr9ss 
' C2 Cc/iapter>. press 

will make a given chapter into a press file, which is then be printed on the Dover printer. The cz program 

automatically inserts the figures in their proper places. To get the entire manual, simply use the commands: 

cd /usr/sun/doc 
cz manual .press 

1.2. Related Documentation 

1. The architecture of the MC68000 procesor and a description of the processor chip can be found in 
Motorola's User's Manual [13]. There are several books describing the 68000 architecture [9J [10]. 
Most vendor-supplied hardware is described in separate manuals or data sheets. 

2. The hardware manual [1], currently somewhere on Sail, describes tlie processor, ethemet, and 
graphics boards designed at Stanford. Someday we should convert this into Scribe and merge it 
into this manual. , 

3. Th& Documentation for Unix^ can be found in the standard Unix [15] and Berkeley manuals. 
Most of this is stored on the large Unix systems, and available through the man and apropos 
commands. Some specific MG68000 Unix commands are described in the next Chapter. 

4. The Perseus documentation, under [I FS]<Perseus>. Perseus is a distributed operating system, 
currently under development. There are probably a dozen CS246b projects that are related, the 
documentation of which is scattered throught die world. 



Unix is a tradcmaric of BcU Labwatories 
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2. Software Development on Unix 

Currently our development work is being done on a vax^ computer running the Unix operating system. 
Witli any luck, Unix may soon be running on the 68000 itself. 



2.1. Organization of SUN directories 

Common SUN software is stored in subdirectories under one master directory. For example, on the 
Stanford VAXes Shasta and Diablo, this directory is /usr/sun. The following is a description of these 
subdirectories, using the notation relative to /usr/sun, or whatever it happens to be called on your system. 
Every source file should contain a comment near the begining describing tlie author, date, and purpose of the 
file. 



yadmin 



Administrative records, and a wishlist. 



./bin Binary files for Sunix commands. Complain to Vaughan about documenting Sunix. 

./bootfile ^ Standard boot-format files. The production copies of stand-alone programs reside here. 

This is the default directory for the SUN boot server. *Test" versions are put in the 
subdirectory test, not in the main directory. 

./dm Files to support the Motorola Design Module. Includes .dl format files of some 

programs that run on the design module. Read chapter 5 for more information on the 
support for the design module. 

./dm/lib Objectlibrary files specific to the design module. 

./dm/mclude Header files specific to the design module. 

./doc Overview documentation. The document you are reading now resides here. Some other 

docimientation exists in subdirectories of this. 

./doc/graphics Description of a Raster-op level graphics package. 



./include 



Header files, used by the #i ncl udo directive of the C preprocessor. See section 2.3 for 
more information. 



./lib 



Object libraries. These arc searched by the -1 option of cc68. Some of tliese are 
described near the end of this chapter. 



./man68 



Master copies of manual pages describing Unix commands. See next section for details on 
these commands. 



VAX is a trademark of Digital Equipment Corporation 
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./monitor .dl files for making monitor proms. Sources are hidden under ysrc/monitor. 

./src Some sun-related sources, subdivided into the following subdirectories. These should 

correspond to the debugged, "production" versions of programs. Each subdirectory 
should have a makefile describing how to compile sources in it; the result of the 
makef n e should be the bootfiles in ./bootfUc or ./bin. 

./src/cmd Commands that run on Vax and Sun. Further divided into subdirectories for some of the 

important tools like the compiler, loader, etc. 

./src/diag Sun hardware diagnostics. These consist of a memory test, an ethernet interface test, and a 

graphics board test. 

./src/games Source for some games. Most of these run on a "dumb" terminal, instead of using the 
graphics board. 

./src/graphics Graphics demostration programs, and a Raster-op package. 

./src/4ibc Sun libca sources. Further subdivided into the following subdirectories. 

./src/libc/crt C run-time support This is the routine which sets up the stack and calls the ma i n function 
of a program. 

./src/libc/emt Emulator traps into the prom monitor. 

./src/libc/gen General functions. This includes string manipulation, string conversion, etc. 

./src/iibc/stdio Standard 10 fimctions. Currently this all goes through the terminal line. 

./src/libc/sunstuffSUN Processor specific part of the library. Isn't all this stuff? Please complain to vaughan 
about this. 

./src/libc/test Floating point tests. Has anybody ever used this? 

./src/libc/unixstdio 

Some Unix stdio stuff, never used for anything. 

./src/monitor PROM Monitor sources. Complain to Jeff that the up to date versions are kept in his 
private directory instead of the proper place. 

./src/mut Multi-user Pup Telnet This is the program that runs on "Ether Tips", and in a multi- 

window terminal program located in ./src/ tty. 

./src/tty Multi-window terminal program. 

./unix68 Nu terminal Unix from MIT - Optional. We should put the LucasFilms Unix there 

someday, if we ever get it. 
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2.2. Unix Commands Relevant to 68000 Software 

The following Unix commands arc used for MC68000 software development Ail of them arc documented 
in chapter 1 of the Unix manual. This listing may be obtained using the Unix command apropos 68, 



as68(l) -Assembler 

cc68(l) - General C command 

ccom68(l) - Portable C compiler 

ddt68(l) - A symbolic debugger and disassembler 

dlx(l) - Down line load protocol handler 

dl68(l) - Download file generator 

ld68(l) - Linking loader 

lorder68(l) - Object library utility 

imi68(l) - Print name list of object files 

o68(l) -optimizer for assembly language 

pc68(l) - Pascal* compiler (similar to cc68) 

pr68(l) - print extended statistics on .b file 

rev68(l) - reverse byte order .b and .68 (b.out) files 

rl68(l) - print relocation commands in a .b file 

size68(l) - prints sizes of segments in a .b file 



2.2.1 . Compiling with CC68 

These commands are meant to mirror the standard Unix commands without the "68" suffix. For example* 
the normal C command is cc, and the coresponding MC68000 command is cc68. This is the command most 
users will be concerned with. Its function is to take the files named as arguments and do whatever needs to be 
done to make them into a runable program. For cc68 to work properly, you should follow some simple 
naming conventions. File names should consist of a short module name, followed by a suffix consisting of a 
dot and one or two letters. The suffixes are listed below: 

C language source programs. These are typed in and edited by the user with any editor. 

Pascal*, (or regular Pascal) source files. See the Pascal* reference manual [8] for a 
description of the language. 

Header files, usually consisting of declarations and macro definitions which are accessed by 
the#include directive. Some usefiil header files are described in section 2.3. 

Assembly language files, produced by tlic compiler or written by hand. Compiler produced 
. s files are usually not seen by tlie user, except for detailed optimization or debugging. 
These used to be called . a68 files, but cc68 used .s, which unfortunately conflicts with 
all other assembler files, such as VAX assembler files. 

Binary files, the output of the assembler. 

(none) Tlic default output of die linker is the file name b.out Usually an explicit output file will be 

specified with the -o option, the name of tlie program without any suffix. If the file is 



.c 
.P 

.h 

.s 

.b 



11 DnCHMBHR 1981 



6 



SUN USKRS' GUIDE 



generated on a machine with non-standard byte order such as a v/oc, the . r format should 
be the final result 

.r Byte reversed files produced by rev68, ready to be loaded over ethemet. In actual 

practice, the . r suffix tends to not actually appear. 

. d 1 Motorola down-line load format (called "S-records"). Used to load over slow serial lines. 

The three most often used options of cc68 are -o <nanie>, which means the the output will be named 
<name>, -c which specifies a separately compiled module, and -0 which causes the optimizer to be invoked. 




V >n«I© 



I F/7e./s ) 

Figure 2-1: Developing Software with Unix 

The make program simpifics die construction of programs using several modules [6]. Just create a file 
called makefile (or Makef ile) under tlie directory witli your programs to be compiled. The makefile 
consists of dependencies and commands, dependencies consist of a list of files to be made, followed by a 
colon, followed by a list of files upon which the others depend. Commands begin with a tab and end with a 
blank line. Thus, for example. 
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ethertip: enet.b tip.b 

cc68 -r -o ethertip enet.b tip.b 

tip.b: tip.c 

cc68 -0 -c tip.c 

enet.b: enet.h enet.c 

cc68 -0 -c enet.c 

is a makefile for a program called etherti p that consists of two modules, tip and enet. 'ITie first command 
line links the two modules together. The tip.b file depends on the corresponding source tip.c, and will 
be compiled with the optimizer because of the -0. The enet . b module is compiled from tlie corresponding 
. c file, but also includes a header ( . h) file. 

After creating the makefile, you can edit any or all of your sources, and just say make to remake the 
program. The make program reads the makefile, and infers the necessary commands from the write dales of 
the files. Continuing the above example, if we were to edit the enet . h file and perfonn a make command, 

the enet . b module would be recompiled and the program relinked with the following commands.' 

cc68 -0 -c enet.c 

cc68 -r -o tfp enet.b tip.b 

2.2.2. The 68000 Assembler 

The 68000 assembler (as6S) takes file, s and produces file, b, a non-text file containing an 8-word header 
and segments for text, data, symbols, data relocation commands, and text relocation commands. The header 
contains two words of magic numbers, the sizes of die text, initialized data, uninitialized data, symbol, and 
relocation-command segments, and die entry point (the start address of die top level routine). The listing 
might by slightly helpful in debugging; the values it gives for symbols however are incomplete. Uninitialized 
data symbols have no values in the listing, while all other values are relative to the start address, determined at 
load time. 

Assembler options: 

•'6<digit> Used for debugging the assembler only. The digit gives some indication of the level of 



debug printout 



-G 



Only put external symbols into the output binary file. 



Treat any undefined symbols as globals. They must be eventually resolved by the loader. 



-L name 



Put die listing file into the file name. The cc68 command normally puts the listing in a 
file with a name of the form nawie. l s. 



-1 



Produce a listing in filename, list, or other file if - L is given. 
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-o nam Put the output in the file «a/«<? instead of ///^/laAne. b. 

-p Print the listing on standard output. • 

-s Put the symbol table In the file 1 i st . out. The loader's symbol table is probably more 

useful, since it is made after relocation. 



2.2.3- The 68000 Linker 

Tlie^gOOO linker (1 d68) produces a file called b . out, in a similar format to file, b. The primary tasks of 
the linkier are to develop a symbol table for all of its inputs, and execute the relocation commands to produce 
absoluUecode. The output contains the same eight- word header as in file, b, text, data, and tlie symbol table. 

Loadkr options: 

-D dsz Set the size of the data segment to rfsz. It is padded with zeros if too short. 

-d ' Force the common segment to be defined (overrides second part of -r) 

epi Make ept the entry point of the program. Otherwise the first address of the code segment 

is used. 

Search the library file named /usr/sun/1 ib/1 ibwamc. a. A library file is searched 
only as its name is encountered on the command line, so the order may be important. Note 
there is no space between the - 1 and the name. 

-M Create a file listing the symbols and their values insym.out. 

-0 filr Outpuris iiamedy2/e instead of b. out. 

- p Preserve relocation bits so that die output file can be used for input to 1 d68 in a later run. 

Also prevents final symbol definitions for conunon symbols, and supresses "undefined 
symbol" diagnostics. 

-s Strip the output file of all symbol table and relocation bits. 

-T addr Start the code segment at ^f/rfr. 

-u sym Add ^ywUG the symbol table. This is used when loading enitrely from a library, since you 

need at least one symbol reference to extract a "root" module. 

-aversion Specifies the version of the 68000 environment to assume. Currently tlie only available 

options are - vm for the Design Module, and the default for the SUN. 

-X Discard locals starting with L (weaker than -x). This option is used by cc68 to discard 

internally-generated symbols. 
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-X 



Discard all local symbols from tlie output file. 



2.2.4. Producing Loadable Files 

The binary produced by the linker is converted into a file suitable for down-line loading by most PROM 
monitors with die dl 68 program. The only dl 68 option is -T st which specifies st as the starting address 
The input file must be the first argument; options other than -T are ignored in silence. Symbol tables are 
preserved. See section 5.3 or 3.3 for information on actually loading the design module or SUN processor. 
The rev68 program takes linked b . ou t files and does some final byte-reversing if the target machine has a 
different byte order than the current machine. 



2.3. Header Files in /us r/sun/include 

Several useful header files are located in the /usr/sun/include directory. This directory is searched 
automatically by the C preprocessor when you use^include directives. 

amd9513.h 



b.out.h 



Definttions for the AMD9513 timer chip. Jeff and several others have their own private 
versions of this file. Please complain to them about it, and the relationship with timer . h. 

Defines the format of a b . out binary file. Note that although you use tlie same header 
file, the bytes are reversed between the 68000 and the VAX, So you must run rev68 to 
convert between the two. 



buserr.h 



chars.h 



A structure definition matching the information pushed on the stack of the 68000 on a bus 
error, and the "function codes" as described in the MC68000 User's Manual [13J. 

Defines some mnemonics for control characters. 



framebuf.h Definitions for the SUN Multibus frame buffer. See Chapter 4 for more infonnation. 

graphics.h Definitions for a "Raster-Op" graphics package which is frame-buffer independent See 

Chapter 4, and the separate manual on this for more infonnation. 

graphmacs.h Some graphics macros for the SUN frame buffer. Most people will probably want to use 
the graphics package instead. 

lisp.h A simple Lisp system defined in macros that map into C. Complain to Vaughan about this. 

m68000.h MC68000 mnemonic definitions for registers, and some Macros for performing special 

instructions like setting the interrupt level from C. 



m6821.h 



Motorola 6821 Peripheral Interface Accessory. This is a fancy name for the parallel I/O 
ports on the Design Module. 



m6840.h 



Motorola 6840 Timer. This is the timer on die Design Module. It is so complicated 
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nobody here has ever figured out how to use it 

Motorola 6850 Asynchronous Communication Interface Accessory. This is the device that 
connects your terminal to the Design Module, and the Design Module to a computer. 
Almost everybody else calls it a U ART. 

Definitions for die SUN Multibus Ediemet interface. 

Vaughan's version of the definitions for the memory map on the 68000 processor board. 
Please complain to him about the duplication with pcmap . h and noprotecl . h. 

Definitions for the NEC 7201 double Uart. This is what connects your tenninal on the 
SUN board, <inalgous to die Motorola 6850c 

More stuff for the NEC 7201 Uart, like die addresses and some uUlity macros. It is so 
complicated it takes two files! 

Yet another memory map file. This one defines the protection codes. Complain to 
Vaughan about the strange name. 

Jeffs version of the memory map definitions. Please complain to him about Uie duplication 
between this and map . h and noprotect . h. 

Defines a macro for interrupt handlers. Please complain to Vaughan about the strange 
name. 

Definitions for die Signetics 2651 Uart. This is the chip used on our octal Uart boards. 
Defines some symbols for the 68000 status register. 

Some undocumented definitions for some kind of Unix-like standard I/O. Complain to 
Vaughan to document it. 

Defines the emt codes supported by the SUN Prom monitor. 

Some macros for manipulating the old wire-wrap version of die memory map. Complain to 
Jeff to get rid of this. 

Some macros to do storage allocation of fixed size objects. Complain to Vaughan about 
the strange name. 

Some more definitions for the SUN processor board dmer. See also amd9513.h. 
Some symbols defined for die MC68000 interrupt and excepdon vectors. 
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2.4. Libraries 

Some 68000 libraries are stored in tlic directory /usr/sun/lib in the form of arcliives compiled and 
assembled as .b files. The standard ar program, as described in the Unix manual, is used to manipulate these 
archive files. The cc68 command normally searches the library /usr/sun/l ib/1 ibc .a automatically. 
Some of these functions are similar to the standard C library, but others are still under development. The 
sourcesshouldallbeunder /usr/sun/src/1 ib or/usr/sun/src/1 ibc. 

2.4.1. The C Library 

In the interests of greater portability of low-level code between the design module and the SUN processor, 
some board independent I/O ftinctions have been written and installed in libc.a. Any references to 
put char, printf, and getchar, for example, will invoke ftinctions to perform the I/O on the 
"cansole" terminal Similarly getenv will behave rather like its Unix counterpart, with geterrv( "TERM" ) 
returning "sun", etc. 

There is also a set of lower-level functions in the standard C library. The device types are determined at 
link time, by supplying the appropriate set of routines, either as parameters to cc68 (for example, -vm). AU 
uart functions begin with 'line* and have the line number as their first argument By convention, line number 

0 is the local terminal or keyboard, and line number 1 is connceted to a remote host This trades off size of 
the library for size of the calling code and a littie speed. 

char 1 ineget(//>ie} 

Get a character from line assuming the receiver is ready. 

ltneput(/me, drr) 

Put character c/ir on line /we, assuming the transitter is ready. 

int line ready tx(///ie) 

True if the transmitter is ready on line line to accept another character to be transmitted. 

int linereadyrx(///2e) 

True if die receiver is ready on line /we. 

1 i ne ser V i ce (proc^^) 

Set the given procedure pointer to be liie internipt service routine for both lines, proc 
should be declared with thereentrant() macro, described in section 23. 

1 inearmrx(/i/ie) ' 

Enable receiver interrupts on the given line. The interrupt service routine should already 
be set up. 

1 inedisarmrx(///2e) 
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Disarm receiver interrupt on the given //>ie. 

linearmtx(//«e) 

Arm transmitter interrupt for line 

1 inedisapmtx(/(>i€) 

disarm transmitter interrupt for line ///le. 

1 ineresettxint(//«e) 

Reset a transmitter interrupt, when there are no more characters to print 

1 ine reset (//ne) 

Reset ///le. Default to interrupts disarmed 

It is the responsibility of the individual libraries to deal with the problem of independently setting and 
clearing control bits for arm and disarm. The user need not keep track of the bits explicitly. 

The meaning of 1 ineready=: ==0 is that the line is busy for whatever reason, whether no carrier, no 
DTR, no CIS, or reception/transmission proceeding. It is assumed that all operations will be with 8 data bits, 

2 stop bits, and nq^parity bit 

No provision is made for detecting Uart errors. It may be reasonable to attempt low-level error 
correction/detection in lineget and possibly lineput; however this should not be considered a substitute for 
higher level error correction/detection (checksums on downloading, perhaps use of Dialnet). 

2.4.2. The PUP and Leaf Libraries 

The PUP [5] library is stored in /usr/sun/lib/libpup.a. Since these routines are all described in 
section 9 of the Unix manual, (available online with the man 9 command), they are not described in detail 
here. cc68 will search tliis Tibrary if it is given the - 1 pup option. 

The -lleaf option on a cc68 will search the leaf library, stored in /usr/sun/1 ib/1 ibleaf .a. I^f 
is a remote file access protocol, based on the Sequin reliable packet stream protocol. There are Leaf servers 
running on most large timesharing machines. Documentation of the library is in 
/usr /local /doc/ leaf /Leaf User. press6Shasta. 
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2.4.3. The SUNOS Library 

The SUNOS library is stored in/usr/sun/lib/libsunos.a, and can be searched with thc-lsunos 
option of cc68. The SUNOS library is discussed in chapter 7. 

2.5. The 68000 C and Pascal Calling Sequence 

The stacic grows downward, towards smaller addresses. Two address registers are used to access the stack, 
a6 (the frame pointer) and a7 (the stack pointer). The stack pointer is the standard one for the 68000, in that 
BSR (Branch to SubRoutine). JSR (Jump to SubRoutine), and PEA (Push Effective Address) all use it. Note 
that exceptions do not default to it, but rather to the System Stack Pointer, a register not accessible in user 
state^ ■ 

The code produced by the C and Pascal compilers result in a6 serving as a pointer to a linked list of stack 
frames. A stack frame is a region of the stack associated with the calling or activation of a function. Stack 
frames are stored contiguously on the stack. Stack frames have five components; from low addresses (top of 
stack) to high they are: 

1. Locals. These may be of any size, and will occur in the reverse of their declaration order (or, 
perhaps more mnemonically, in their declaration order going away from the Frame Center). ITiey 
will be contiguous to within the word alignment restriction, i.e. non-chars will be aligned at even 
addresses. If the first local is char its address is the same as though it were a short (a quirk of the 
compiler). The compiler also allows one additional byte beyond the last local. 

2. Registers. This region contains some subset of the registers d2-d7 and a2-a5 saved on entry. The 
registers saved are those actually used. The convention is made that C subroutines always 
preserve these registers, as well as a6 and a7, but change dO,dl,aO and al unpredictably. The 
optimization is such that this convention holds down to the statement level (or even lower!). 
Alignment is on multiples of 4. Because of the additional byte allowed by the compiler for locals, 
that byte and up to 3 more (the worst case being when the locals actually declared end on a 
muldple of 4) are aU unused. 

3. Frame Center. This contains a 4-byte pointer to the Frame Center of the next stack frame down 
the stack (i.e. at a higher address). 

4. Return Address. This contains the caller^s 4-byte return address. 

5. Arguments. The arguments passed by the caller arc implicitly cast as ints before being pushed on 
the stack. Hence they are stored in consecutive 4-bytcs regardless of their actual size. They are 
stored in calling order, with the first argument closest to the Frame Center. It follows that the 
order in which they are pushed is the reverse of the order they are written. 
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2.6. Hie "S-Record" Down-Line Load File Format 

A . dl file consists of a series of records each having seven components: 

1. Tie letters. 

2. A ^e, a digit in the range 0 to 9. 

3. Atwo digit (one byte) count, giving the number of bytes in the record. 

4. An address, either 16-bit (two hex digits) or 24-bit (three hex digits). 

5. /i-i or n-4 bytes of data, depending on the address type, where n is die count given in 3. 

6. A one-byte checksum. The checlcsum test is that the sum of the bytes in items 3 through 6 must 
be congruent to 255 mod 256, i.e. must have OxFF in the least significant byte. 

7. The end of the line. 
The types are as follows: 





Use 


Features 


0 


Header 


Ignored by MACSbug, and no longer generated 


I 


Data 


Two-byte address, bytes in hex (not used) 


2 


Data 


Three-byte address, bytes in hex 


8 


Trailer 


lliree-by te address, bytes in hex 


9 


Trailer 


Two-byte address, bytes in hex (not used) 



If a header is given it goes at the start. A trailer must appear, and goes at the end. Tlie rest of the file 
consists of data records. The header is currently ignored. Each data record is loaded into memory starting 
with the address specified in in the record, provided it passes the checksum test The trailer serves two 
functions: to terminate reading, and to load PC with the trailer's address, giving a mechanism for defining the 
entry point of a program. 
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3. Using the SUN Processor 

Tlie SUN processor is a powerful single board computer containing a Motorola MC68000 CPU, memory 
with management and parity, and some I/O devices. The board plan is illustrated in figure 3-1. 



32 K bytes EPROM 



Dual Uart 



16- bit Input Port 



68000 Processor 
8 MHz 



Timer 



Men^ory Control 



Clocks, Logic, etc. 



Memory 
Management 



IEEE 7 96- Bus Interface 



256K bytes 
dynamic RAM 
with Byte parity 



J L 



Figure 3-1: Layout of the SUN Processor Board 

3.1 . Introduction to the SUN ROM Monitor 

Most use of the SUN processor involves interacting, at least initially, with the ROM-resident monitor. The 
following sections discusses the purpose of the monitor, and how to use it Note: tlie discussion below 
assumes (occasionally) the use of the PC-board version of the Sun Processor, which has a two-level memory 
map. Users of the Versions 1 and 2 wire- wrap boards can probably deduce the points of difference; however, 
neither of these boards will be supported in the future. 

Although the primary function of the ROM monitor is to provide a simple console for the workstation, 
there are a few features which affect the user programs that mn under it. For simple programs, especially 
those using standard I/O routines, the characteristics of the monitor should not be important. However, if a 
program makes direct use of interrupts or I/O devices, a few critical details arc relevant. 
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3.1.1. What is the monitor? 

It is useful at tliis point to give a brief desci iption of the operation of the monitor (SunMon), mostly to 
provide a context for understanding the few rules imposed upon user programs. 

The monitor has four major fimctions: initialization on processor reset, memory refresh, providing 
Emulator Trap service (see section 3.8), and "intelligent console" facilities. Although the last may be the most 
visible, the first two are the most important; the processor would be essentially unusable without them. 

When the processor is reset (either when the "Reset" switch is hit, or when the power first comes on), 
SunMon gains control. It initializes the on-board I/O devices (timers and Darts), sizes memory, sets up the 
Segment Table and Page Table, initializes the parity state of the on-board RAM, creates the RAM refresh 
routine, and initializes the interrupt and exception vectors, After this, control is transferred to a module that 
manages the ''console" functions. 

Memory refresh is done by the processor because it actually does not cost anything in terms of 
performance, and because it greatly simplifies the hardware design. The memory is refreshed by simply 
reading 128 consecutive words every 2 milliseconds (some memory chips may need slightly different refresh 
rates). This is done by executing a routine consisting mostly of NOPs. This routine is stored in RAM, and so 
a malfunctioning program may damage it and thus cause havoc (since the contents of memory will be lost). 

The console functions are implemented with fairly straightforward routines that conmiunicate with the user 
via the two on-board Uarts. If a Frame Buffer is available, the monitor will use it for output instead of the 
console UART (command are still entered via a keyboard connected to the UART.) 

In versions of SunMon that support ethernet bootstrapping, the console also uses the 
Multibus Ethernet interface. In any case, all I/O is done using "busy-waits", and the code runs at the highest 
interrupt priority. Therefore, if a user program is interrupted with the "Break" key on the console terminal or 
with some other exception, the monitor will run correctly unless its global data area has been damaged. Also, 
if tlie user program is then continued, it should be unaffected by the interruption save for the possible loss of 
somel/O. 

3.1.2. Absolute Rules 

From the precceding section, it should be fairly obvious that one major rule is necessary to prevent a 
monitor crash: do not trash the refresh routine or monitor globals. In general, the first two pages of memory 
arc reserved for the monitor and should never be written by user programs; however, user code may want to 
change exception vectors occasionally. It is legal to change any exception vector, except the "Level 7 
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Autovector", at 0x7C (used for refresh timing), and any "User Interrupt Vector", between 0x100 and Ox3FF, 
inclusive. The refresh routine and monitor giobals live in the region reserved for "User Interrupt Vectors", 
because the Sun processor board does not support their use. 

Certain other exception vectors (for example, the vector for a Breakpoint trap) are used by the monitor. 
However, it may be possible to alter these without dire results. Any program altering the refresh routine and 
interrupt vector must take responsibility for doing proper memory refresh. 

One other rule is important: user programs should not modify the Context Register directly, but should use 
the facilities described in section 3.8. 

3.2. Getting Started 

3.2.1 . Initializing the Workstation 

The first step in using the SUN processor is making sure it is turned on. There is probably a switch labeled 
"ON" and "OFF*. It will work better if the power switch is in the "ON" position. (Version 2 processors have 
a "power** light on their control panels.) A terminal should be connected to the communications cable 
extending from the processor. If you have a serial line to a host computer available, it should also be 
connected to the communications cable. Finally, if an ethemet interface is present, it should be connected to 
an ethemet transceiver cable. 

There is one switch, labeled "Reset" (it may actually be a power on/off switch.) Pressing and releasing llie 
Reset switch should be done after initial power-up of the machine, and whenever you want to really reset 
everything. After a few seconds, the monitor should identify itself on the console terminal, with a message- 
looking like 

Sun Network Monitor, Version 0.9 - 0x20000 bytes of memory 
The word "Network" may be omitted; certain commands pertaining to the ethemet only work witli network 
monitors. If this message does not appear, and the "halt" light is not lit, check the terminal's status and 
connection. If the halt light is lit, and if repeated use of the Reset switch has no effect, your hardware may be 
broken. The Reset operation will probably destroy the contents of memory. 

Pressing and releasing the "Break" key on the console terminal switch causes a trap (also known as an 
"Abort") to the monitor so that debugging commands may be given. You may continue an aborted program; 
see the C command, described in section 3.3. 
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3.2.2. Some Sample Programs 

Tlic following are some iiscfiil programs available in the default bootfile directory. Most of their sources 
are in appropriate subdirectories of /usr/sun. Tliey all can be loaded and started with the n name 
command of the monitor. [Note: the locations of source files here arc all wrong!) 

cyl4 A short program that displays four circles that move diagonally on the screen. A good 

example of simple animation. Runs only with a frame buffer, of course. 

edp A simple ethernet diagnostic program. Source is in /usr/sun/diag/edp. You miglit 

have to load the . d 1 version, especially if your ethernet interface is not working. 

kal A kalidescope program, originally written in BCPL for the Alto, and transcribed into 

C. Really impressive graphics demo for the frame buffer. Source is in /usr/sun/derao. 
Also see i kal , an interactive version. 

meintest A memory diagnostic, sources in /usr/sun/diag/memtest. When your workstation 

has nothing better to do, it could run this to help check for faulty memory. 

mo n h e 1 p As described below, this is a file which prints out a quick summai7 of the available monitor 

commands. Note: various versions o/monhelp exist, corresponding to the various versions 
of the monitor. On version 0.7 and later monitors, monhe 1 p2 is the program to run. Please 
bug Jeff to cleanlhis up! 

rect Another graphics demo for the frame buffer, The sources are located in /us r/sun /demo. 

This just does some "random" raster-ops in rectangles on the screen, f rect is an 
impressively fast version of rect. 

s u n b f d A program which lists the "standard" bootfiles available via the ediemet bootloader, 

suntty A program which simulates a multi- window terminal on the frame buffer, with a separate 

PUP telnet connection in each window, llie source to this and the tty program is in 
/usr/sun/tty. 

tip A multi-user PUP telnet program. If you have any octal Uart boards in your machine 

they may each have a PUP telnet connection, as well as the primary terminal. 

tty Another version of the multi-window terminal program. This one uses the serial line 

instead of the -ethernet interface, so you talk directly to one host. 



3.2.3. A Simple Example 

We will now step through how to write, compile, load, and nm a simple program. First, we use our favorit 
editor to enter the following program into the file /mnt/smi th/tes t . c: 
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main() 

■.,{-■ - . ' 

/* 

* A simple tst program for the SUN workstation 
♦/ 

printf( ''Hello world!\n" ); 

y ■ 

We now compile the program with the following command : 
cc68 -r -o test test.c 

We then go to our workstaion and type the command to load and nm: 
>n /mnt/smith/test 

Hello world! • 
> 



3.3. The ROM Monitor Commands 

The command format understood by the monitor is quite simple. It is: 
<verb><space>*[<argument><return>] 

The <verb> part is always one alphabetic character; case does not matter. <space>* means that any number of 

spaces is skipped here. <argument> is normally a hexadecimal number or a single letter; again, case docs not 

matter. As indicated by //, the argument portion may be optional. When typing commands, <backspace> &nd 

<delete> (also called <rubout>) erase one character, control-U erases the entire line. 

The commands are: 

"Open" A-register « (0</i<6). See the discussion below of "open". 

Set a breakpoint. You will be prompted with the old breakpoint address; give the new 
address at which you want a breakpoint trap instruction inserted. 

Continue a program. The address addr, if given, is the address at which execution wiU 
begin. 

"Open" D-register niO<n<7). 

"Open" the word at memory address addr, odd addresses arc rounded down. 

F Bootfile name Load, but do not start, a file via the Ethernet. ITie program can be started with tlie 6 
command. Normally, the current PC is set to the entry point of tlie loaded program. Of 
course, this command is only available on network monitors. 

G addr Start the program by executing a subroutine call to the address aJ^/r if given, or else to the 

current PC. 

H a minimal amount of help will be given; just a short list of commands. On network 



An 
B 

C addr 

D n 
E addr 
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monitors, this actually involves boot-loading a help program via the etliernct If the 
ethcrnct interface is not working, no help is available. 

I mode set Uart operation mode. 'A' means your terminal talks to the monitor, 'B' means your 

host computer talks to the monitor (not very useful if directly invoked), and T' means that 
you talk to the computer ('Transparent" mode) until you hit the transparent mode escape 
character (initially set to control/shift/six or control/up-arrow) followed by a "c". *S* 
toggles the use of the Frame Buffer as the console output device; i.e., it selects it if it is not 
being used, and selects console UART otherwise. The 'S' option has no effect if tliere is no 
Frame Buffer present 

K "Soft Reset": resets the monitor stack and the default escape character. Useful after 

exceptions or other anomalous situations. This may confuse the monitor if a breakpoint 
trap is set 

L Host-command This sends Host-command to the host computer, does an implicit I B, and sends a \ to the 
computer to indicate that it is ready to be downloaded. Tlie Host- command is normally 
dlx file.dl, which will put the terminal back into normal mode when the file is 
downloaded. 

Mm On tlie SUN-1 processor, "open" Map register m. On the SUN-2 processor, "open" 

Segment Map register m. 

N Bootfde-name Load and start a file via the Ethernet Bootfile-name is the pathname of the file to be 
bootstrapped. It should be in .r format produced with the -r option of cc68 or the 
rev6 8 program. This command is only available on network monitors. 

0 addr "Opens" the byte location specified. The byte vs. word distinction is a problem on the 

Multibus, since die convention on byte ordering within words is different for Multibus 
addresses. '» 

P p On the SUN-2 processor, "open" Page Map register p. On the SUN-1 processor, this is 

used to set the PID (Process Identification) register to p. 

R "Opens" the miscellaneous registers (in order) SS (Supervisor Stack Pointer), US (User 

Stack Pointer), SR (Status Register), and PC (Program counter). SS may not be altered. 

S S-record This causes the monitor to accept the S-record. Normally done by the host computer in L 
mode, this responds with a two-digit record count and one of L for length error, K for 
checksum error, or Y for success. 

X char set the transparent mode escape character to char. Because of the way that the parser treats 

spaces, tlie escape character cannot be set to be a space. 

"Opening" a memory word, map register, or processor register means that the address or register name is 
displayed along with it current contents. You may then type a new hexadecimal value, or simply <return> 
to go on the next address or register. Typing Q will get you back to command level. For registers, "next" 
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means within the sequence D0-D7, A0-A6, SS, US, SR, PC. For example, the following commands set 
location 1234 to 5678, and register Dl to OFOO. The user types tlie underlined parts, with a return a the end of 
each command. 

> e 1234 • 
001234: 23CF? 5678 
001236: 0000? fl 
H 

DO: 00000001? 

Dl: 00000231? OfOO 

D2: 01203405? fl 

> . 

3.4. Loading Programs 

One of the primary uses of the monitor is to load programs into the processor's memory. Programs can 
either be loaded via a serial line connected to a host computer, refered to as "down-line loading", or via the 
ethernet, refered to as "net-loading". In usual terminology, "down-line loading" often refers to any mediod 
loading one computer from another, but it is useful to make the distinction here. Net-loading is usually much 
faster, but both modes have their advantages and disadvantages. 

3.4.1. Down-line Loading 

Down-line loading involves transferring a program file over a serial line. The file must be converted into a 
format known as "S-records" before transmission, either using the d 168 command or the -d flag of cc68. 
Files in this format usually have a . d 1 extension. 

Suppose the file we want to load is called test . dl , Assuming that you have used "transparent" mode to 

log into the host computer and have set your working directory properly, you should then "escape" from 

transparent mode. Then, issue the command 
L dix test.dl 

This will transmit the command dix test. dl to the host, and then cause the monitor to accept fiiture 
commands from the host If all goes well, you should see a string of periods on your terminal, and then a 
monitor prompt when the load is done. You may then start your program with the 6 command; normally, 
the current PC is set by the downloader to be the entry point of the program. 

If the new monitor prompt comes immediately, this means that the dix program detected an error, and 
your program could not be loaded (probably because it could not be read). If the periods stop coming (one 
should print every few seconds), this means that the loader has hung. You should hit Reset or the "Break" 
key, change to transparent mode, and type control-G (or your normal intemipt character) to abort the dix 
command. You may also have to issue the Unix reset command to put your terminal line back into a 
normal mode. 
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Attempting to down-line load a file not in S-rccord format will probably cause strange behaviour, although 

the d 1 X program attempts to detect this error. Also, you may omit the . d 1 extension in most cases, i.e., 
L dix test 

should be equivalent to 
I dix test.dl 

unless both test . dl and test are S-record files. 
3.4.2. Net-loading 

If you have a network monitor, and an ethemet interface, you may load programs over the ethernet 
Program files to be loaded in this way should be in "reversed b . out format"; this means that a file produced 
by the loader should be converted using the rev68 command, or the -r flag of cc68 should be used in 
compilation. Files in this format often have a .r extension, but sometimes they have either a .Boot 
extension, or no extension at all 

Suppose you want to load the file /mnt/person/test.r. You should give the command 
F /mnt/person/test.r 

You should almost immediately get a new monitor prompt. You may then start your program with the G 

command; normally, the current PC is set by the net-loader to be the entry point of the program. 

Alternatively, you may give the "load-and-go" command 
N /mnt/person/test.r 

which will load the file and immediately start it. 

If the net-loader fails to load the file, it will print a period and try again, up to a reasonable limit If it gives 
up, it will print Timeout and return to the monitor. Even if a file is not succcssflilly loaded, it is quite 
probable that the memory has been altered. 

If you get an exception when net-loading a file, it may be because there is a hardware problem, but it is 
more likely to be because you loaded something not in reversed b.out format. Of course, if the exception 
occurs with the load-and-go (N) command, it may have been caused by your program. 

The network bootstrap scr\'cr rimning under Unix interprets filenames not beginning with */' as relative to 

/usr/sun/bootf ile. Thus, 
N memtest 

will load the file /usr/sun/bootf i 1 e/memtest. In fact, tlie H (help) command in the network monitor 
is equivalent to doing an N monhelp. 

Normally, bootload requests are broadcast to all servers on the net. However, you can specify the name of 
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the host you want to boot the file from by proceeding the filename with the hostname and a colon. For 

example, 

N Shasta imemtest 

will get the program "memtcst" from the PUP host named "shasta". 

Note that it is not possible to load more than one file at a time with the net-loader. If you want to load 
more than one file (presumably into different areas of memory), you must use the down-line loader. 



3.5. Memory Mapping 

The SUN processor is provided with a map so that you can map pages of 2K bytes anywhere in your 
address space. The structure of the virtual address is given in figure 3-2. SunMon, during initialization, sets 
up the Segment Table and Page Table in a "standard" way which makes all memory and I/O devices 
available to user programs. User programs may change these maps (although page 0 and whatever pages 
likely to contain the top of the Supervisor stack should not be remapped, or memory rcfiresh may fail). 
However, for simple programs tlie initial mapping may be best left alone. 
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Figure 3-2: Memory Mapping on the SUN Processor 
Each actually existing page of on-board RAM is initially mapped so that its physical and virtual addresses 
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arc identical. This means that each segment, starting at segment 0, is fully mapped (up to the limit of 
available memory). Segments are only initialized for context 0. Segment protection is set so that both 
Supervisor and User modes have Read, Write, and Execute access to every segment 

Two other physical address spaces are mapped into the memory address space. The Fii'st 64K bytes of 
MultiBus 1/0 space is mapped at the top of the virtual address space, and extends for 32 pages (64K bytes). 
Thus addresses from IFOOOO to IFFFFF get mapped to the Multibus I/O space. The Ethernet interface and 
most commercially available Multibus I/O devices use this space. 

The rest of the high megabyte of mappable address space is mapped as MultiBus memory. Address from 
100000 to lEFFFF are mapped to Multibus memory space addresses 0 to OEFFFF, respectively. This is 
where the frame buffer resides. 

The physical address space (the 24 bit addresses used in the internal bus) is divided into eight parts, as 
descnbed below. 

0 - IFFFFF Mapped address space, as described above. There is usually 128K to 256K bytes of on- 

board RAM, with a limit of 512K. This space can also be mapped into the Multibus I/O or 
Multibus Memory space. 

200000 - 3FFFFF On board PROMO. See the discussion below on "boot State". 

400000 - 5FFFFF On board PROMl. 

600000 - 7FFFFF The on-board double Uart. Channel A data register is at 600000, command register at 
600002, Channel B data is at 600004, and B command is at 600006. 

800000 - 9FFFFF On board Timer chip. 800000 is the Data register, 800002 is the Command register. 

AOOOOO - BFFFFF Page map in SUN-2, FID register in SUN-1. 

cooooo - DFFFFF Segment map in SUN-2, page map in SUN-1. 

EOOOOO-FFFFFF Context register in SUN-2. 

In "boot state", the state of the system after reset, read and execute accesses to any location Oxxxxx in 
mapped addresss space are redirected to come from the corresponding location 2xxxxx (in the PROMO 

address space), but write accesses to the mapped address space go to on board RAM. Also, all interrupts 
(including normally "non-maskable" ones) are inhibited. In this way it is possible to initialize RAM just after 
reset. Boot state is exited on the SUN-1 processor by writing to OxEOOOOO, and by writing to the PROMO 
address space on the SUN-2 processor. 
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When the monitor is initialized, it sets tlie Supervisor Stack Pointer to 0x1000, and tlie User Stack Pointer 
to the top of available memory. User programs may change these registers, providing that they do not cause 
the supervisor stack to overflow into unmapped address space. 

More exact detail on the memory mapping, as well as constant definitions uscfiil for C programs, may be 
found in /usr/sun/include/sunmmap. h. (Note: sunmmap.h currently describes only Version t 
processors,) 

3.6. Traps 

The monitor initializes the trap vectors so that it gets control of any exception or interrupt. Some, such as 
the memory refresh timer interrupt, are handled internally. Others have special meanings (for example, the 
"trap -#1" operation is treated as a breakpoint trap). For exceptions or interrupts not internally handled, the 
monitor will print a message such asException: Tr and then return to command le veL 

The messages printed use a two-letter code; here is a list of these codes and their meanings. 



II Illegal Instruction: an illegal instruction code was executed 

ZD Zero Divide: division by zero 

Ch Check: a CHK instruction faulted 

TV TRAPV: a TRAP V (trap on overflow) was taken 

P r Privilege violation: attempt made to execute privileged instruction while in user state 

UO Unimplemcnted 0: an opcode 1010 was executed (emulator trap) 

Ul Unimplementedl: an opcode 1111 was executed (emulator trap) 

Un Unassigned: trap was made to unassigned vector. 

LI. L2, 13, L4, L5» i6 

interrupt Autovector: an Autovectorcd interrupt was taken at one of levels 1 through 6. 

Tr Trap: a trap instruction was executed. 



Several exceptions arc handled specially by the monitor. A breakpoint trap (instaiction "trap #1") causes 

the message 

Break at pc 

to appear. A trace trap evokes the message 
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Trace trap at pc 

to appear. Use of the "Break'* key causes 
Abort at pc 

to appear. In each case, the pc shown is that of the next instruction to be executed. For fiirtlier information 
on the use of these three uraps, see section 3.7. 

A Bus Error trap (usually caused by attempting to access non-existant memory or devices) gives the 
messa^ 

Bus Error: address access-address at pc 

Similarly, an Address Error trap (usually caused by attempting to access a word with an odd address) causes 

the monitor to print 

Address Error: address access'address At pc 

In cither case, the access-address is useful in helping to determine the cause of the trap. It is possible to 

continue from these traps, although the apparent effect of the faulting instruction is not always defined 

"User Interrupt Vectors*', locations 0x100 through Ox3FF, are not available for use as such on the SUN 
board due to the hardware design. For this reason, this area of memory is used by the ROM monitor for 
storing globals and the RAM refinesh routine. 

3.7. Tracing programs 

The monitor provides several facilities for tracing program execution. Tliey are quite primitive, however, 
and basically require you to understand your program at the machine code level. However, if you have a 
symbol table listing of your program (created using nm68), you will be able to at least know where each 

3.7.1. Breakpoint traps 

The use of a Breakpoint trap (BPT) allows to run a program and regain control when execution reaches a 

certain location. The monitor currently can only maintain one breakpoint trap at a time. A breakpoint trap is 

set using the B command; after giving this command, you will be given the address of the previous BPT and 

prompted for a new address. For example. 
Break 001000? 

means that a BFT is already set at location 1000. At this point, you could type a 0 to clear the BPT, a return to 
leave things as they are, or a new address at which to set a trap (the old trap will be cleared). 

If you had gained control of your program before setting the trap by using the "Break'* key, you might 
want to continue it using the C command. Otherwise, you will probably want to start the program using the G 
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command. Execution will then proceed until the trap is reached, at which point you will get a message such as 
Break at 001000 

At this point, you may examine the location at which you set the BPT and you will find that it contains the 
original instruction. You may clear the BFf or set a new one at this point. If you do not, you may continue 
using tlic C command, which will execute the "broken" instruction, then reset the BFl' and continue. If you 
give an address to the C command, the breakpoint trap will not be reset, unless for some reason you talce a 
Trace trap. 

If you load a new program while a BPT is set, the monitor will normally be able to detect this. On the other 
hand, if you give the K command ("Soft Reset") while a BPT is set, and then set a new one, wicrd things will 
happen if the first trap is taken. Jeff should fix this! 

3.7.2. Trace traps 

' The support for Trace traps (single-stepping a user program) is even more minimal tlian the support for 
Breakpoint traps. To set a trace trap, you should use the R command, proceed to tlie Status Register (SR), and 
alter it so as to inclusive-OR it with 0x8000. Similarly, the trace trap can be cleared by ANDing the value of 
SR with0x7FFR 

Once the trace bit is set in the SR, you should then give the C command to continue the program (the G 
command cannot be used in this way); to start a program with the trace bit set, give the command C starling- 
address. Subsequent steps may be made by using the C command without an argument. 

For complex reasons, it is not possible to single-step after a Breakpoint trap is taken, unless you first clear 
the BPT. Once you have stepped one instniction, you may dien reset the BPT. Jeff may fix this sooner or 

■ ■ 

3.8. Emulator Traps 

The ROM monitor is able to provide several services to user programs via "Emulator Traps" (EMTs). An 
EMT is a convenient way of entering the monitor which does not depend directly on the absolute addresses 
used. Instead of executing a j b s p instruction, a program wishing to use the emulator first pushes a "trap type 
code" on the stack, and then executes a trap #15. instruction. In most other respects the operation is 
identical to a function call. 

The services provided by the EMT facility fall into three categories: information, I/O, and memory- 
management. Some of these, such as the memory-management operations, are restricted to supervisor mode. 
The following section gives the C-language calling sequences and descriptions for the EMTs; asscmbly- 
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language definitions arc available in the file /us r/ sun/ i nc I ude/sunemt . h. 

In general, if one of these functions encounters an error condition, it will return the value -1. In particular, 
attempting to execute a trap reserved to supervisor mode while operating in user mode will result in an error 
-return. 

3.8.1. Information EMTs 

int emt** t1cks() 

Returns the number ofmilliseconds since the monitor was last booted. This is incremented 
whenever memory is refreshed, at least every 4 milliseconds. The accuracy is sufficient for 
time-of-day uses, if the crystal on the processor card is working right 

int emt*- getmemsize() 

Returns the size of the on-board RAM in bytes. 

int €mt*- version() 

Returns die "version" of the ROM monitor; the most significant byte is the major version 
number, the next byte is the minor version number. For example, 0x0105 corresponds to 
version 1.5. 

3.8.2. I/O EMTs 

emt*- putchar(c) 
chap c; 

Prints the specified character on the Console. If c is a linefeed or a carriage return, then it 
is followed by a carriage return or a linefeed, respectively. The I/O is done using busy- 
waiting. 

chap emt*- getchar 

Returns the next character typed on the Console keyboard. Normally, the character is also 
echoed on the Console. The I/O is done using busy-waiting. 

setecho(f lag) 

int flag ■ ■ 

Controls whether characters input from the Console by emt<- getchar ( ) arc echoed or 
not; they arc echoed if and only if f 1 ag is true. 

3.8.3. Memory Management EMTs 

These EMTs are provided for use by die kernel of an operating system, and arc restricted to supervisor 
mode only. They are necessary because it is not possible to access the segment registers for one context while 
running in another context Since there may be no properly initialized segments in a given context it is not 
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possible for the kernel to simply switch contexts before changing the segment map; tliis operation must be 
done by code running entirely in ROM and processor registers. The memory management EMTs provide this 
service. Note tliat it is essential that the context register not be changed except via tlic EMT described below. 

short emt<- getsegmap(cxt .segno) 
int cxt ; 
1nt segno; 

Returns the contents of segment map entry number segno in context number cxt. 

emt«- setsegmap(cxt, segno, entry) 
int cxt ; 
int segno ; 
short entry; 

Sets segment map entry number segno in context number cxt to entry. 

int emt*- getcontext() 

Returns the current value of the context register. 

emt^ setcontext(cxt) 
int cxt; 

Sets the context register to cxt. 

Here is an example of the use of the emt*- ticks global to derive an accurate timer» counting seconds. 
(Warning: a previous version of this example contained a program logic error that rendered it inaccurate!} 



main( ) 
{ 

long MextTick; /* value of RefrCnt at next second */ 

long ThisTick; /* temporary; used to avoid a race */ 

long seconds =0; 

ThisTick ' emtticks(); /* initialize loop invariant */ 

for (;;) { 

printf ( "Time is %d\n" .seconds++) ; 

NextTick = ThisTick + 1000; /* predict next second */ 
while ( ThisTick < NextTick ) /* busy-wait */ 
ThisTick = emt__ticks( ) ; 

} 

} • ,. , ■ ■ ■ 
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4. The SUN Graphics System 

The SUN graphics system is a high-resolution bit-mapped frame buffer on one Multibus board. The 
general organization of the graphics board is illustrated in F"igure 4-1. There is only a small amount of 
hardware assistance to perform the simple high bandwidth operations (called "RasterOps"). lliis results in a 
simple, yet flexible graphics device, with high enough performance for sophisticated user interfaces. 



* Bit-Manipulation 

* X/Y Addressing 

* Graphical Object Cache 

* Next Address Generation 

* Graphical Object Selection 

* Function Selection 



Hardware 



Software 



Host 




RasterOP 




Fram© 






Processor 





Hardware 


^ 


Buffer 




— H 



Video 
Monitor 



RasterOP unit performs read-modify-write cycle 
Destination in frame buffer 

Source operands can come from frame buffer or host computer 



Figure 4-1: The SUN Graphics Board 

4.1 . Graphics on the SUN workstation 

As shown in Figure 4-2, the nominal viewable area of the screen is 1024 pixels high and 800 pixels wide in 
"portrait" mode (similar to the Alto display). Other configurations (like the Xerox Large Format Display) are 
also possible with appropriate changes to PROMs on the graphics board. ITic Large Format Display is 808 
pixels high and 1024 pixels wide. This display is compatible with tlie display used in the Xerox "Star" 8000 
and "Dolphin" 1100 workstations. The points are addressed by X and Y (column and row), starting with (0,0) 
in the upper left comer of the screen. From one to sixteen consecutive pixels may be read from or written to 
the frame buffer in one memory cycle (one microsecond). 



Figure 4-3 illustrates the concept of "RasterOp", as developed by Newman and Sproull [14]. A RasterOp 
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Portrait" Mode 

799.0 



0.0 



"Landscape" Mode 

X 



0,807 



1023,1023 



Size: 
Visible: 
Invisible: 
Updates: 



1024 * 1024 pixels 
800 * 1024 pixels 
224*1024 pixels 
16 pixels/cycle 



1023,1023 

Size: 1024 * 1024 pixels 

Visible: 1024 * 808 pixels 

Invisible: 1024 * 216 pixels 
Updates: 16 pixels/cycle 



Figure 4-2: The SUN Graphics Screen 

sets a destination rectangle on the screen to a bit-by-bit boolean function of three variables: its original 
contents (DST), a source rectangle (SRC), and a repeating bit pattern (PAT). The SUN graphics system 
allows all 256 possible Raster-OP fiinctions, although only a few are used in practice. 

For example, to clear the entire screen, the constant fiinction 0 is applied to the viewable rectangle. To 
flash a certain window, the function NOT Dst is performed on that window. To write a character, the Src 
function is used, while NOT Src writes the character inverted (black on white), Dst OR Src overwrites 
(paints) the character, and Src OR Pat writes the character with a background pattern. There should be a 
standard graphics package to provide access at the RasterOp level. 



4.2. Detailed Operation of the Graphics Board 

The graphics board decodes 20 bits on the Multibus memory address lines, in the fields shown in Figure 4- 
4. By encoding these operation bits in die address, repetitive operations like generalized rastcrOps can be 
done very quickly. There is a patent pending on this design. 

Up to eight graphics boards may share a single Multibus backplane, with the high 3 bits selecting the 
board. Each board occupies 128K bytes of Multibus memory space. 
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"RasterOP" Model (Newman & SprouH): 
DST *■ f (DST. SRC, PAT) 



Destination 



Source 



Pattern 



RasterOP 




Dst Constant 

Dst <- Src 

Dst ^ Dst OR Src AND Pat 

Dst Dst AND NOT Src 

Dst *■ Dst XOR Src 



Figure 4-3: "RasterOp" Concept 

Some mnemonic definitions for the frame buffer can be found in the f ramebuf . h header file (see section 
2.3 for more information). All the symbols begin with the letters GX. To perform an operation on the 
graphics board, you must combine the bits togetlier, cast the result to a short*, and reference the pointer. 
There are also a few combined symbols that can appear in C assignment conexts. See the end of this section 
for some examples. 

The GXupdate bit (bit 16) is on if the frame buffer is to be modified. Usually several operations are 
perfomed with this bit off, to set up the control registers and one of the coordinates. Then this bit is set to 
actually perform the desired modification of the frame buffer. 

Bits 14 and 15 select the operation. If they are set to GX none then the data on the data bus is not used 
(although an X or Y address may be loaded in this cycle). If they arc set to GXother s then one of tlie four 
control registers will be written with the data. If they are set to GXpat, the pattern register (sometimes called 
the "mask") will be loaded from the data bus. If they are set to GX source, the data bus is loaded into the 
"source*' register. This is the normal case for copy operations. 



When GXothers is specified, the control register number is given in bits 1 and 2. GXf unction loads tlie 
function register from tlie low-order eight bits of tlic data bus. I'hc function register can be thought of as a bit 
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Figure 4-4: Graphics Board Address Decoding 

vector, indexed by 2*^05 t+2^Src+2^Pat. For example,^ GXinvert = 0x55 inverts the destination, 
GXcopy =OxCC copies the source to the desitination, and GXcTear =0 clears the destination. 

GXwi dth is the register that determines the width of the RasterOps. It is loaded from the low order 4 bits 
of the data bus, with 0 meaning 16, so its valid range is from 1 through 16. If it is less than 16, the high-order 
bits of the data in the source and pattern registers will be significant on RasterOps. GX con trol loads the 
interrupt level (low order 3 bits), intcrmpt enable, (bit 3, symbol GXintEnable), and video enable (bit 7, 
symbol GXvideoEnable) bits from the data bus. Accessing the last control register, GXintClear, must be 
done once after every video refresh interrupt to clear it, when it is enabled. 

lliere are four pairs of ten-bit address registers (sometimes called "cursors"), selected by bits 12 and 13. Bit 
11 selects either X or Y of the pair, and bits 1 through 10 of the address are loaded into the selected address 
register. Note that every read or write reference to the graphics board has to load one of these address 
registers, while it might or might not (depending on the GX update and operation code bits) modify the 
frame buf!bf. 



The low order bit (bit 0) of the address must always be zero. This design was meant to be used efficiently 
with auto-incrementing addressing modes. For example, the following function displays an 8 by 8 "cursor" at 
the given position: 
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/* screen coordinates of upper left corner */ 



D1sp1a^Cursor( x, y ) 
short X, y; 
{ 

static short cursor[] = { 0x9200, 

0x5400, /* Left justified bit array •/ 

0x3800, 

OxFEOO, 

0x3800, 

0x5400, 

0x9200, 

0x0000}; 



register short 

♦cursorPointer = cursor; 

•xPointer = (short • )(GXUnitOBase | GXselectX), 
*yPointer = (short •)(GXUnitOBase \ GXupdate 

I GXsource j GXselectY>: 



register short junk; 



/* something to move */ 



GXwidth « 8; 
GXfunction - GXinvert; 

xPointer += x; 
yPointer +* y; 

♦xPointer = junk; 



*yPointer++ = *cursor++: 

*yPointer++ = *cursor++; 

•yPointer++ = *cursor-»-+; 

*yPointer++ * •cursor^-*; 

*yPointer++ = •cursor++; 

*yPointer++ = *cursor++; 

*yPointer++ = *cursor++; 

*yPointer++ = •cursor++; 



/• Each of these is one •/ 
/• 68000 instruction */ 
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5. The Motorola 68000 Design Module 

The MC68000 Design Module is a board with an MC68000 processor, memory, and some minimal I/O 
devices, for designing and evaluating the MC68G00 processor. It was deisgncd for tlic EXORciscr development 
system, but we use it with a serial connection to a VAX and a standard terminal. 

Before actually using tlic 68000 design module, read the Design Module User's Guide [12], a black booklet 
by Motorola that describes MACSbug, the monitor that resides in PROM on the design module, and the I/O 
devices available. 

5.1. Preparation of Programs 

Write the program as an ordinary C program, called <name>, c. Do not rely on <s td i o . h> - it docs not 
apply to the Design Module. [Vaughan has rigged up some of die C library for the design module, and it 
should be referred to herej 

Section 2.3 describes some header files that can be included in C programs, and section 2.4 describes some 
libraries available. As described in section 2.2.1, you probably want the -vm option on tlie cc68 command 
Unc. v'"" • - 

5.2. Compilation 

To compile a single program which can be loaded into the 68000 design module (the Motorola-supplied 

board), use the command 

cc68 -vm -d-^-jft <fTaroe>.dn <name>.c 

Error messages will be printed on your terminal. Errors may arise at any of several stages: preprocessing, 

compilation, assembly, and loading. To understand these stages see section 2.2.1; for the moment assume that 

you have got your program to compile successfully on the VAX. You now want to down-line load and test 

your program, which you will find in your working directory as <name> , d 1 . 

5.3. Down-line Loading 

Downloading is the process of getting your program into the 68000 from the VAX or wherever you keep 
your program. While it is necessary to compile on tlie VAX, the result of compilation can be put on any 
computer. Get your 68000 to the point where you can talk through it (in transparent or P2 mode) to the 
computer where your file is. Type t A to return to MACSbug (the 68000 board monitor). Note that this sends 
tAtX to the host; before downloading you will need to compensate somehow for tliis. A carriage rctura will 
suffice on most systems. To send a return to the host without reentering transparent mode, type 
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(asterisk return) to MACSbug. This will send tlic return. In general typing 

will send the text to the host; you will not see the reply if any. See section 5.8 for more information. 

The downloading command is RE (for REad). This command waits for the host to start typing out your 
file; when this happens it reads it into memory, then at the end halts and types Normally REad checksums 
each line of input; each failing line generates an error report on your terminal. 

RE may take any of the following arguments: 

= text As it takes a certain dexterity to persuade the host to delay typeout until you do the 

tA*<return>RE there is an option to send a line of text to the host as part of your giving 
the REad command. Thus if you say to Unix 

RE «dn foo.dl 

then the file f oo . dl will be loaded into the 68000. The dll program simply pads each 
hne with a few nulls to allow loading at 9600 Baud. 

X This option displays the data being read. It permits you to watch the file being loaded so 

that you can see what progress is being made. For example if the host dies (so becoming a 
heavenly host) you will have no indication of this without the X option. A disadvantage of 
the X option is that any checksum error report will disappear off the screen within 24 lines 
of typeout, so that you must watch the whole loading process if you want to be sure of 
catching checksum errors. 

-C Thisj^ption ignores checksums. Useful only on rare occasions. 

With all options, your command would look something like 
RE -cx»dii foo.dl 

5.4. Running 

To run the program type 

■ G'lOOO 

to MACSbug. If the program terminates normally it will type an asterisk, the MACSbug prompt, to indicate Uiat 
it has returned to MACSbug. 

If G is given without an argument, execution starts with the virtual PC (contents of location 400, see 
below). This permits an interrupted program to be restarted from where it was interrupted. 
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5.5. Debugging Aids 

MACSbug offers debugging facilities that are moderately well documented in the design module manual. 
Here are the highlights. 

5.5.1. Display 

You may display die contents of any register merely by typing its name. Names arc PC SR SS US DO 
Dl ... D7 AO Al ... A7. You may see all D registers by typing D, and similarly for A. 

To Display Memory, type: 
DM Kaddressy 

(in hex, all values are in hex). The 16 bytes starting with that location arc typed out. To see more than 16, 
supply the number as a second argument. Thus DM 1200 100 will fill most of your screen with bytes 1200 
tol2FF. 

* The memory values you display are real, but the register values are virtual. The register values are those 
that held when your program was last interrupted; they are kept in memory locations 400 to 44B inclusive, in 
the order PC SR D A US (where A7 is taken to be SS, the system stack pointer, rather dian US, presumably 
since it happens to be dumped while in system mode). 

5.5.2. Setting 

To set register R to value K, type R K, as in D3 247. These settings will take effect on the processor 
proper as soon as you type G. To set all of the D registers, say D : and MACSbug will show you each in turn; 
for each you should either type return if you want it unchanged, or a value, return, if you wan to change it to 
that value. 

To Set Memory, say 

SM <address> <vaJue> <value> .... 

The values will be stored starting in that address, immediately. Values may be from 1 to 8 hex digits. Each 

value is stored in the next few bytes, as few as possible consistent with the number of digits (no zero 

suppression). Thus 

SM 4000 12 34567 
DM 4000 

004000 12 03 45 67 . . . 
SM 4000 00004321 6547 
DM 4000 

004000 00 00 43 21 65 47 .. . 
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5.5.3. Breakpoints 

To set a breakpoint use the command 
Bli <a(idres$> 

Your program will stop when it reaches that address. This is implemented by placing a 434F (TRAP 15) 
instruction at that address, not at the BReak command but at the G command. The instruction is removed 
after it has had its effect; it will be restored again at the next G. Note that CALL, described below, docs not 
install the breakpoints. The eflFect is that you cannot see a breakpoint merely by looking at memory; to tell 
what breakpoints arc set type BR without an argument. 

To clear a breakpoint, type: 
BR '<adilress> 

To clear all breakpoints type 
BR CUAR 

To sec what breakpoints are set type 
,BR 

If you should reset the computer while your program is running, all the breakpoints will stay put since 
MACSbug will have forgotten where it put them. When a Trap 15 is encountered for which MACSbug has no 
record, it types ERROR and halts your program. You will have to fix it yourself, either with SM or RE. 

You may delay a breakpoint so that it takes effect only on the nth time it is encountered by saying 
BR <address>:n 

On the /2tli encounter it breaks. When the program is restarted n is forgotten about, i.e. n reverts to 1, the 
default To restore « give the command again. 

To set a temporary breakpoint, one that clears itself when encountered, give the command 
6 TILL <address> 

The address gives the stop (unless some other breakpoint or the end of the program is encountered first). The 
start is the virtual PC. 

6.5.4. Tracing 

To single step through a program, say TR. The program will begin execution from virtual PC, and halt 
after one instruction, typing out the trace information (see below) followed by 

When the prompt is : * it means that you can type carriage return as a synonym for TR, so that you can 
conveniently trace a series of step. If you ty pe MACSbug commands at any point, the prompt reverts to *. 

TR n will trace n steps, printing trace information on each step. To trace n steps without any printout at 
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all.doTD CL (see below). 

5.5.5. Trace Display 

Whenever MACSbug interrupts your program by reaching a breakpoint or after one instruction in the case 
of tracing, or when you type TD, it types out selected information. The default is that it types out the contents 
of all Uie registers. You may modify this default as follows. Each TD command is sticky, i.e. its effect Is felt 
till you give another TD command. 



TD 


CL 


Displays nothing. Cannot be combined as in TD CL PC 


TD 


ALL 


Restores the default. 


TD 


DO 


Displays PC (similarly TD PC.TD SR.... but not TD DorTD A) 


TD 


DO .0 


Do not display DO (similarly TD PC.O.TD SR.O, ...) 


TD 


DO.l 


Display least significant byte of PC 


TD 


DO. 2 


Display lower word of DO 


TD 


DO. 3 


Display lower three bytes of DO (only effective after TD C L) 



The short forms are helpful in two ways: they give a less cluttered display, and they permit tracing to 
happen faster. TD CL permits muUistep tracing (as in TR n) to proceed independently of tlie terminal speed, 
though not at full machine speed unfortunately. To see the final register values when tlie tracing stops do TD 
ALL then TD. I ^ ■ ' 

You may also turn words of memory into pseudoregisters which can then be displayed along with the real 
registers. To define say the-2-byte word at address 4564 as pseudoregister M5, say 

W5.2 4564 

You may now refer to M5 in the TD command, as in TD M5, or TD M5 . 1, or TD M5 . 0, each of which 
displays the appropriate amount of this 2-byte register. Pseudoregisters may not be larger than 4 bytes. 

A pseudoregister may be relative to an address register, thus: 

W3.4 4(A6) 

The location is 4 past what A6 points to. A6 is the stack-frame base register for C programs, and 4(A6) is 
where the return address lives, so that you can monitor the calling address while tracing, as a supplement to 
the PC. Similarly tlie arguments are (in order) 8(A6), C(A6), 10(A6), while the locals are (in order) -6(A6X 
-A(A6), -E(A6), ... provided they arc all integers (4 bytes); compensate accordingly if not. Function 
arguments are always converted to the C type int. If the routine uses register variables, subtract 4 for each 
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register variable in computing these offsets. 

5.5.6. Symbols 

To assign the symbolic name FOO to a value, say 
SY FOO <value> 

To see the value of FOO say 

■ SY FOO. 

To see all symbols, say 

.:SY . • ^ •■ 

See section for a discussion of the symbol table produced by the compilation/loading process. This table may 
be operated on with the above symbol manipulating commands. But Macsyma it is not 

5.5.7. Numeric conversions 

The CV (ConVert) command will display both hex and decimal values of its argument Preceding the 
argument with & or nothing denotes decimal, with $ hex. The printout observes these two conventions. 

Thus: :;. . ■ -"^ 

CV 49 ■ 
$2D « &4$ 

You may evaluate a sum of two numbers by using , as infix plus, as in 

CV 45.3 
$30 = 448 

This does not work for differences or for three elements at once (do it in stages). 



5.6. Symbol Tafcrfes 

Symbols are generated and loaded automatically along with the program. They reside in the region from 
6BA to FFF. To print out the symbol table type SY (see the section earlier on dealing with symbols from 
MACSbug). Loading a new program destroys the old symbols (that's the best we can do with MACSbug, sorry). 
Sometime an option will be installed permitting you to produce .61 files without symbols, to prevent this 
probleou . ■ 

Resetting MACSbug also appears to make the symbol table go away. This is much less destructive tlian 
reading in another symbol table however. All that needs to be done to restore the invisible symbol table is to 
set the word at 576 (remember this as 24 squared, even though 576 is really hex) to the first empty word of the 
table, which can be found by printing out the table itself The starting address of the table will be found in 
576 (and in 572) since this is the pointer to the first free table entry; when MACSbug thinks the table is empty 
tliis pointer coincides with tliat pointing to the beginning of the table (572, or really 570, these are 32 bit 
pointers but it is convenient to work with them as 16-bit ones). 
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The format of each entry in the tabic is an 8-byte name followed by a 4-byte value. The name is left 
justified, padded with blanks, starts with an upper-case letter or period, and may only contain letters, digits» 
period, and the symbol (at least if you want to be able to refer to them when talking to MACSbug). 
Knowing this it is generally not too difficult to spot the end of tlic table by relying on tlie Ascii part of the DM 
printout. 

You should set 576 to the exact first free entry if you expect to be adding symbols manually, as in SY FOG 
33. Otherwise you can err on the low side by up to 11 bytes when in doubt or haste. 

B.7. Disassembly 

The DM command is not much use in following code in memory. To make it easier tliere is a disassembly 
program, dasm.dl on /usr/sun. which when loaded will run in the 6000-7000 region of memory. 
Provided your programs do not reach into that region you can leave the disassembler there permanently. 

To inspect locations starting from n, enter n into DO and type G 6000. You can now single-step through 
the code by typing any character but Q. Each step will display the next instruction and the address it is at 
The program will return to MACSbug either on encountering an illegal instruction or on your typing Q (for 
Quit - it must be capitalized, but that's how you have to talk to MACSbug). 

Dasm understands symbols if present in the symbol table. When loaded it brings its own symbols with it, 
so you have to load the program to be debugged after you've loaded Dasm. (This will be fixed soon. IHa! " 

5.8. P2/tA 

P2 mode on the 68060 is a software and hardware combination that splices out the 68000 from the terminal- 
host padi it normally intercepts. This is accomplished when you type P2 to MACSbug by setting tlie RTS bit 
of ACIAl high. Random logic attached to this bit then routes input to one serial connector of the board 
directly to the output of the other serial connector. Terminal-host traffic then proceeds at a rate dependent 
only on the host and the terminal. MACSbug monitors the terminal to host traffic (it is physically possible to 
read the traffic in eitlicr direction) and exits from P2 mode when tA is seen. This assumes that the speed of 
ACIAI is set to agree with that of the traffic, which it need not be. The tA is the default escape; to set some 
other escape, say tV, type . 

P2 tV 

Since the tA is seen by the host and MACSbug simultaneously, there is no way in this arrangement to prevent 
sending the escape to the host, so like any wise jailbird you should plan your escape carefully. MACSbug adds 
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insult to injury however by transmitting tX to the host after seeing the tA. Unlike the tA, the tx is not a 
default but is in Prom, so learn to live with it. 

If you run your terminal at 9600 baud and the host at 1200 baud, a sensible arrangement for people at 
home, you will hit the obvious snag when you use P2. As should be clear from the above discussion, while 
you must change your terminars speed, you need not change ACI A I's speed. 

A more "brute force" way of getting out of transparent mode is to press the reset button on the design 
module (the black one). This will clobber the registers and reset MACSbug» however. Pressing tlie red abort 
button does not leave P2 mode, but makes MACSbug forget tliat P2 mode is on, leaving MACSbug in a 
confused state. ; 

5.9. Memory Layout 

Memory in the Motorola Design Module is laid out as follows: 

0-3FF Interrupt vectors 

400-6B9 MACSbug variables 

6BA-FFF MACSbug symbol table 

1000-7C00 User space 

7E0()-7EFF User stack (more may be taken if necessary, clearly) 

7F00-7FFF System stack (the system/user distinction is vague on this board) 
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6. An Insider's Guide to SUNet 

This chapter describes the current state of network communication around here. Ethernet is used to 
connect computers within the same building, with repeaters and gateways being used to temporarily extend 
the Ethernet between buildings. Arpanet connects several machines, and some are connected to Telenet* 
Tymnet, and other ad-hoc networks. Eventually we hope to provide other communications media for the 
intermediate distance needs, like 10 Mb standard Ethernet, Fiber-optics, point to point serial links, packet 
radio, or a broad-band cable TV compatible system. The rough topology of tlie network is illustrated in 
Figure 6-1. For more information see the references [7] and [16]. 

This information is really quite voladle, so it is imperative that this chapter be kept up to date. Each 
description below consists of the computer you want to come from, followed by a colon, and the command 
that invokes the given program. A short description includes the hosts you can go to witii that program* 

6.1. Remote Terminal Programs 

VAV: telnet host 

Pup user telnet [5] to any Pup host with a telnet server running. Currently this means 

Shasta, Diablo, Helens, Lassen, DSN, and Sail. When the gateway is working you can get 
to Sumex and "Tiny," die 2020 at the Medical Center. Documentation is obtained with the 
man telnet command. Telnet has transcript and shell escape options. Type code 036 
followed by c to get out (usually control-t or control-shift-N). Pup telnet has gateway 
capabilities to the Arpanet. If the host name you give is not in die PUP network directory, 
or there is no PUP route known to it, it will connect to the telnet gateway at Sail and try the 
Arpanet 

Sail: r chat Pup user telnet as above. Control-meta-q to get out Currently it simulates a very simple 
terminal, so you can't even do things like backspace. 

Alto: telnet host 

Pup user telnet also, based on the chat program. Simulates a simple screen tenninal. on 
which vi almost works. Also available as a boot file. 

Alto: talk host The talk program gives you multiple windows (stacked vertically), and you can am 
cmacs or vi in them, so it is currently tlic default for Unix telnet servers. You can create a 
window of 52 lines, and then specify te rm b i gtal k to Unix to get a big screen. 

Alto: dmchat host 

Another terminal program using Pup telnet protocol, based on die Chat program. This one 
gives you one big "datamedia" window, which works well with Sail. If you are using 
dmchat, tell Unix you are a dm2599. You must have tiic fixed width font snai 1 10 . al 
on your disk for this to work (or an entry on your user. cm). 

Sail: dial diablo 
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Figure 6-1: Topology of SUNet 

Simple 1200 baud serial line to Diablo. Loses characters routinely. Use only when all else 
fails (which is all too often tlicse days). Get out with control-meta-q. 

VAX: sail / score 

sail Rins on Diablo, score runs on Shasta. 1200 baud serial link. Use telnet sail or 
telnet score instead. 

Scorertelnet shasta 

This currently goes through Sail's telnet gateway. Typing this command will be guaranteed 
to get you there in the best possible way (directly over die etliernet in the fiiture). There is 
also a possibility of using the 1200 baud serial link. ITiis and the score program are 
mutually exclusive. Loads down score badly. Exit with control t c. 
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6.2. File Transfer Programs 

VAX: ftp host Pup user ftp. Talks to any Pup server FTP, currently this means Shasta, Diablo, Helens, 
Lassen, DSN, Sumex, Tiny, and any alto running ftp. Documented with man ftp. 

Sail: r pupf tp Pup user ftp. Same as above. Experimental. Preferred way of getting files from VAXcn to 
the outside world. Use type X for 32 bit binary flics. Documentation in 
pupftp. tvr[up,doc]. 

Alto: ftp host Another Pup user ftp, as above. Prefercd way of getting files to Altos. 

Alto: ef tp Simple u-ansfer of files from Sail. Self-explanatory. Now mostly outdated by ftp. It is still 
used for sendind files to the Dover, but that should be done invisibly to tlie user. 

Sail: r ef tp Old, slow, but reliable way to get binary files between sail and ethernet hosts. Say 1 for 
mode, using 1 for left hand bits. 

VAX:eftp e[xr3 host filename 

Obsolete way of getting binary files to/from sail. Be sure to do a man eftp command, since 
there are many obscure options. We ususally use e and often s for binary files and ct for 
text files. For text files the command vtos x (for VAX-to-SaU) abbreviates eftp 
reqtlv sail x, while stov (for Sail-to- VAX) abbreviates eftp xeqtTv sail x. 



Sail: ftp Arpanet-host 

Arpanet ftp. Remember to use ascii mode or right curly braces (as well as other random 
characters) will disappear. 

Score: ftp ftos/ Prefered way of shipping files around the Arpanet 



6.3. Walk Net (Tape transfer) 

VAX:ansi [load] [init vol] [write Jilesi 

Reads ANSI standard labeled tapes. Works with VMS, RSX, RT-11, tapeio (with 
/Format :Ansi), and vaxtap tapes. Text files only. Documented witliman ansi 

Score: vaxtap Writes and reads Ansi standard labeled tapes for VMS systems, also works with the ansi 
program on Unix. Unfortunately it does not handle wildcards, so you need JVlIC files for 
large transfers. 

Score: tapeio Writes and reads Ansi standard labeled tapes for CIT, also is supposed to write DEC 
compatible labeled tapes. You can exchange tapes with tlic ansi program with the 
/format : ans i option. You must run the tape 1 abel program on a new tape to write a 
label. 

Score: <su-net>taput 

A really kludgy way of getting binary tapes to VAXcn. Use ftp to sail and pupftp instead. 
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7. SUNOS - A Small Operating System 

SUNOS is a compact operating system for the Sun workstation. It manages asynchronous processes, the 
memory map, and interprocess communication. 

Process Services 

spawn( function, argcount, argl, argZ, ,..) 

spawn new process, with stream args 

wait(p) 

wait till p holds (non-busy waiting) 

terminate! ) 

terminate this process 

Stream Services 

char * getc(/-) char *r 

get char from stream r 

getcto(r, v) char *r,v 

get from stream r into char V 

putc(c, w) char c,*w 

put char c on stream w 

int emptyc(r) char *r 

predicate: stream r is currently empty 

char *cstream() 

create a char stream and return its writer 

Corresponding stream services exist for other types of streams, namely short, integer, and reference, for 
which the respective abbreviations s, i, and r are used in place of c(character). 

Storage Services 

char * create(/i) 

create reference to start of new «-bytc buffer 

char ♦ dupref(/7) char *p 

duplicate reference i? 

dispose(i7) char *p 

dispose of reference p 

The put and get primitives use ordinary char* (reference) variables. Thus, to pcnnittwo processes talk to 
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each other, use est ream twice to produce two references, one pointing into each of two new streams, and 
then apply dupref to each reference to produce two more references for reading from those streams. 

Processes may pass references around freely, provided they observe the discipline of using dupref (/?) to 
make duplicate copies of references and dispose (/?) to dispose of those duplicates. A reference may be 
used either for reading or writing so long as it is consistently used for that. Only one reference to a given 
stream may be used for writing, but any number of independent references may be used for reading, 
permitting independent processes to read the same stream each at its own speed. 

A file using SUNOS should #includ6 "sunio.h" and should contain a sunosQ function, which should 
be confined to spawning an initial set of processes and creating and passing streams to them. The spawned 
functions arc animated (brought to life) after sunosQ exits. There should be no mai n () function in the file, 
this being provided by the library. If the user does provide a mai n( ) it will be substituted for the library- 
supplied main, in which case to ensure an orderly startup of sunos it should be modelled on the library 
version, for which the source is in /usr/sun/sunos/sunos .0. 

The library supplied mai n ( ) initializes the stream and process managers and the interrupt handlers, then 
calls ♦-strtcal to start up calloc, and finally exits to calloc by executing a sleep, ♦•strtcal in turn 
initializes calloc and calls the user-supplied sunosQ to create the initial processes, which come to life after 
ma i n 0 goes to sleep. 

The char streams stdin and stdout are predefined and available to user programs. They are initially 
connected to the terminal I/O of die Design Module. They may be set to other streams as desired; their old 
values should be saved somewhere if it is desired to continue to communicate with the terminal. The 
functions putchar and getchar are defined in terms of putc, getc, stdin, and stdout, as usual. 

An example SUNOS program may be found in /usr/sun/sunos/example.c. This example implements a 
quizmaster and a quizkid who fire streams of questions and answers at each other. 

The cdm command will produce the corresponding .dl file, which includes the code from pman.c, strm.c, 
and calloc.c. This file may be loaded and started in tlie normal way, namely via G MAINE. During the 
settling in period, the SUNOS symbols will be loaded along with the user symbols to help the user distinguish 
his bugs from SUNOS's, but eventually they will be omitted in the interests of avoiding cluttering up the 
usei^stable. 

SUNOS is designed to perform best under heavy load, llie total overhead to send and receive one datum 
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on a heavily used stream, averaging in the overhead of context switching and buffer switching, and assuming 
use of register variables and the rcadcharto (as opposed to readchar) primitive, is roughly 20 microseconds on 
an 8 MHz 68000. 

The present versions of strm.c and calloc.c are close to final However the present version of pman.c is too 
trivial to be really robust; the calloc.c facilities, as described in section 7.5, support much more robust process 
managers. 

SunOS implements processes (virtual concurrency), stream-based interprocess communication, and storage 
management for the Motorola 68000 computer. Although the design was done specifically for the 68000 to 
avoid all compromises that portability considerations might have entailed, the semantics of the resulling 
product turned out to depend only on a few architectural features common to many computers, namely the 
existence of program counter, stack pointer, and status register, and the use of interrupts to schedule 
"external*' processes. 

This overview considers Sunos firom a perspective midway between that of a user and an implementor. 
(Implementors sometimes have difficulty presenting a pure user's view too soon after completing the 
implementation.) 

SunOS provides the following services. 

7.1. Process-oriented Services 

Processes provide virtual concurrency. A process may be defined to be a stack (including its cunenl 
contents) togetlier with the current state of the processor. 

Processes fall into two categories, internal and external, distinguished by how they are scheduled by Calloc, 
the Cpu ALLOCator. 

7.1 .1 . External Processes 

External processes are scheduled by interrupts and arc not even known about by Calloc. They run in 
system state, preempting the CPU when their interrupt occurs. Each external process is responsible for 
restoring the CPU to its original state on exit. External processes communicate with internal processes via 
shared memory. The stream services are available to them, but they may also use more block-oriented forms 
of communication. 
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7.1.2. Internal Processes 

Internal processes share the processor under the control of Calloc, a round-robin preemptive scheduler. 
An internal process may voluntarily surrender the Cpu at any time; oUicrwisc at the expiration of its time 
quantum the Cpu will be preempted. 

Internal processes have two components, whimsically called the patient and the physician. The patient is 
the normal part of the process while the physician acts as exception handler. The physician permits diagnosis 
and debugging of erring processes, and is also responsible for preemption, permitting individual 
implementations of both blocking and nonblocking mutual exclusion mcttiods that the process may need to 
survive with Calloc's asychronous preemptive scheduling. (This does not needed for Sunos*s stream facilities* 
which incorporate their own nonblocking mutual exclusion.) 

7.1.3. Patient services 

spawn(p,n,sl,...,sn) 

spawn process p with n streams sl,...,sn 

wmtdo : " . 

wait until p holds (non-busy waiting) 

terminate this process 
crrdr(e) ; 

commit error e 

Medium-level atomicity is also provided for. The patient may at its option run atomically for a limited 
time. In this state preemptive scheduling by Calloc, though not by interrupt driven processes, is inhibited. 
The patient enters atomic state by signalling its physician, typically by setting a global variable called Lock, 
and leaves atomic state by another signal to the physician, typically by clearing Lock. 

(Medium-level atomicity provides an attractive alternative to locking resources in use by a preempted 
process. Such resource locking is both expensive and a source of deadlocks. At the moment of preemption it 
may often be cheaper to finish the critical section than to incur the costs of blocking a process sharing the 
resource prescndy accessed by the preempted process. Higher levels of atomicity may be provided in the 
usual way, with the usual deadlock problems, using medium level atomiqity to implement synchronization 
primitives, for which low-level atomic instructions such as test-and-set may not always be powerful enough.) 



terminateO 



11 DKCEMBRR 1981 



SUNOS - A SMALL OPERATLNG SYSTEM 



53 



7.1.4. Physician services 

The physician services include all patient services except error(e), together with: 

statusO 

supply physician with patient's pc,sp,sr,error code. 

sstatusO 

set patient's pc,sp,sr (rest is directly accessible) 

nmO 

run patient normally 

singlestepO 

run patient for one step 

breakpoint(a) 

set breakpoint at instruction address a 

The status and sstatus services are needed in case the physician has no other way to access the patient's 
program counter, stack pointer, status register, and error code (reason for invoking the physician). The rest of 
the patient state is accessible 

Physicians are expected to be implemented with system-supplied routines as a rule, and are not themselves 
candidates for diagnosis and debugging; this is a strict two-level approach rather than a hierarchical one. 

The physician inherits all the capabilities (read-write-execute access rights) of its patient, together witii 
write capability for the patient's state (cpu registers and stack) and read capability for all code for which the 
patient has execute capability. The breakpoint service provides an additional capability for code. 

7.2. Stream-oriented Services 

Streams provide a form of communication between processes in which one process may write a sequence of 
data into the stream and any number of processes may read that sequence from the stream asychronously. 
The data types supported by Sunos are characters (one byte), shorts (two bytes), integers (four bytes), and 
references (four bytes, garbage collected). Streams are type-homogeneous: only one of the four possible 
types of data may appear in a stream. 

Streams are accessed by stream references, which arc values of type either char*, short*, or int* in the C 
sense. Sunos provides the equivalent of *s-l~ 4- = d for storing a datum d into a stream referenced by s, and 
*s+ + for fetching a datum from a stream referenced by s. (It is not possible however to use *s4- + = d and 
*s+ + directly due to discontinuities in the internal representation of streams and the need to garbage collect 
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Streams^ 

Stream references have many of the attributes of ordinary pointers. They may be assigned to variables, 
passed as arguments to functions, and returned from fimctions. In passing them around however they may 
not be duplicated implicitly, but must be copied explicitly with the Sunos function dupref(s). Thus if the 
assignment s2 = si is performed and then both si and s2 arc subsequently used as references to the same 
stream, the assignment must be rewritten as s2 = duprefl[sl). Pointer aritlimctic is not permitted, nor may 
pointers be compared with each other since distinct pointers may point to the same place in a stream. 

Streams are defined entirely independently of Calloc. They do not take advantage of the atomicity catered 
for by Calloc but rely on nonblocking methods for accomplishing mutual exclusion at all potential interaction 
sites. This permits streams to be used in common by both internal and external processes, reducing the 
variety of communication primitives required in the system. It is possible to perform all interprocess 
communication via streams. It is intended that even transactions that might ordinarily be handled for the sake 
of efficiency by block moves be handled by streams for the sake of uniformity of communication. The 
efficiency question is intended to be ignored by the user and taken care of at the implementation level (see 
section D below). 

Stream services fall into two categories, transactional or data-oriented, and existential or identity-oriented. 

In the following, T denotes the type of the stream, and may be any of c, s, i, or p, each abbreviating one of 
thefbur^pes. 

Transactional Services 

putT(d,s) put datum din streams. Stream version of *s-h-h = d;getT(s) 

get datum from stream s. Stream version of *s-h + emptyT(s) 
return lif stream s is empty, else 0 

Existential Services 

makestreamTO create a stream, return a reference to its start dupref(r) 

make a copy of reference r (a typeless operation) dispose(r) 
dispose of reference r (a typelcss operation) 

Semantically dupref acts as an identity operation, apparently merely returning its argument. Behind the 
scenes a reference count is incremented. When dispose is called a reference count is decremented. Reference 
counts permit garbage collection of storage associated with streams, permitting die user to ignore the details of 
storage management for streams. 
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7.3. Performance Services 

Performance services are services that are scmantically redundant, i.e. arc already supplied by other 
services, but that offer alternative tradeoffs in time and space. ITie advantage of having performance services 
is finer programmer control of program performance. Their disadvantage is tiiat program structure may be 
obscured by the clutter of performance details interwoven with Uiose aspects of tlie program that contribute to 
its semantic correctness. 

The performance services are as follows: 
block() temporarily suspend execution of this process 

s 1 e e p ( ) destnicdve block: d0"d7,a0-a6 not preserved on return 

putTto(£f,5) same as ptitT ( i/, s) ifevaluationofd has no side effects 

getTto(v.s) equivalent to v = getT(s) 

blockQ is semantically equivalent to the empty statement Its effect is to temporarily surrender the 
processor to another process. Eventually the scheduler will return the processor unhanned to the blocked 
process. block() is used by wait(p), which is implemented as {while (Ip) block();}> 

sleepO is a variant of block ( ) which does not preserve registers d0-d7 or a0-a6. On the Motorola 
68000 si eGp( ) is implemented as a system call, trap #2, while block is implemented as push-sleep-pop, 
namely " . 

movemi #/fFf£,spr0- 
trap #2 

movemi #/7FFF.sp8+. 

The two movemi *s together require 290 68000 cycles, or 36 microseconds on an 8 MHz 68000. Thus context- 
switching efficiency may be improved substantially by use of sleep () together witli alternative ways to 
preserve needed registers such as saving them most of them on entry to a body of code that executes 
sleepO repeatedly. For many applications however the load-buffering capability of Sunos should make 
context-switching costs negligible under heavy load. Hence sleep() should be reserved for situations 
involving short back-and-forth exchanges between processes; block () will be adequate for more heavily 
stream-oriented tasks. 

putTm( J, s) is a variant of putT (i/, s) which is expanded in-line instead of as a subroutine call. Since d 
is referred to more than once in the expansion, evaluation of d should not have side effects. For example 
putcm(getc(s),t) will not be equivalent to putc ( cU s) because ge tc ( s) has the side effect of assigning to s. 
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7.4. Performance Characteristics of Present 68000 Implementation 

The performance figures of greatest interest are: 

• Cost of nonpreemptivc (process-initiated) blocking 

• Cost of preemptive sclicduler-initiatcd blocking 

• Cost of preemptive interrupt-initiated blocking 

• Cost of a stream-mediated transaction (combined put and get) 

• Frequency of each of the above. 

Nonprecmptive blocking using b1 ock( ) requires 34 instructions or about 100 microseconds if we assume 
2 microseconds per instruction. The non-rcgister-saving si eep( ) instruction avoids the two movemrs that 
alone account for 36 microseconds; thus s 1 eep ( ) costs approximately 60 microseconds. 

Frequency of nonprecmptive blocking is intended to decrease as system load increases, at least for tasks 
that lend themselves to batching. The use of streams in interprocess communication will often ensure the 
automatic batching of tasks; a process will continue to process data coming from a stream for as long as data is 
available, blocking only when the stream becomes empty. 

Preemptive blocking is performed by requesting the physician to "retire" this process. Normally this costs 
40 instructions more than blocking, i.e. 74 instructions or about 180 microseconds. If the process was running 
atomically then tlie overhead is increased to that required to single step the process tlirough the atomic 
section, approximately-40 iEtstructions or 80 microseconds per step. 

Frequency of preemptive blocking is intended to be very low in comparison to the overhead of preemptive 
blocking. This motivates the choice of a 10 millisecond quantum for Calloc, making the 180 microseconds 
required for preemptive blocking negligible. Whether the additional overhead of leaving an atomic section 
increases this substantially on the average depends on the probability of being in an atomic section at the time 
of preemption. In general this can be assumed to be less than 0.1, and atomic sections can be assumed to be 
less than 10 instmctions long. Then the expected overhead attributable to atomicity at preemption is at most 
0.1*10*0.5*40 = 20 instructions or 40 microseconds (the 0.5 assumes uniform distribution of where in the 
atomic section preemption was requested). 

Interrupt-mediated preemption is extremely cheap: essentially the cost of the exception. The external 
process saves only tliose registers it needs immediately, which is the same protocol observed in the C calling 
sequence for ordinary subroutine calls, whence should not be counted as an additional overhead. 
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The cost of reading and writing data in a stream decomposes into typical and boundary (bufFcr- 
discontinuity) costs. We first give the costs if the efficiency oriented operations arc used, assuming the stream 
pointers and data are held in registers. The typical cost of writing a datum is 4 instructions, while the 
boundary cost is 90 instructions. The typical cost of reading a datum is 2 instructions while the boundary cost 
is estimated at 40 instaictions though has not been checked. With buffers holding say 240 data, the average 
cost of a write-and-rcad transaction is tlicn 4 4- 2 + (90+40)7240, or approximately 6.5 insUTJClions, 
Measurements suggest that tlie cost of a transaction along with a minimal amount of computation on the data 
being transacted (adding up a stream of chars) requires about 20 microseconds on an 8 Mhz 68000, which is in 
line with the analytic prediction if we allow 7 microseconds for the associated computation. 

7.5. Calloc - A CPU Allocator for the Motorola 68000 

7.5.1. Overview 

Calloc, for Cpu ALLOCator, is concerned with allocation of the CPU to "internal" processes, defined as 
processes running in user state at interrupt level 0. In standard operating system terminology this would be 
called a scheduler. Calloc and its senior sibling process, Matloc the Map ALLOCaion run in system state at 
interrupt level 0. The only other processes are the interrupt driven processes or IDP's which run in system 
state at positive interrupt levels, preempting the cpu according to their level. An IDF is visible only to those 
processes with which it shares memory, which normally will be one or more internal processes on the distal 
end of a stream shared with the IDF. Calloc is entirely unaware of the existence of IDP's, 

Calloc has a minimal set of duties which require little code to implement and can be easily performed. As 
such Calloc should be of interest to operating systems theorists as a tractably small object of study, and to 
operating systems implementors as a small, easily implemented, efficient, and effective component of an 
operating system. 

Calloc is dedicated to maximal autonomy of internal processes. The objective is to minimize duties 
performed in system state, thus minimizing the chances of global system failure due to eiTors committed in 
(vulnerable) system state. The autonomy is supported in two ways, one negative and one positive. On the 
negative side Calloc forgoes tlie luxury of access to any space but its own, thereby reducing the vulnerability 
of the system to system-state errors. More positively, Calloc offers enougli services to permit competent user 
state processes to assume duties normally assigned to system state processes. 

The inaccessibility of memory to Calloc turns out to present no serious obstacles to the implementation of 
Calloc. As it happens none of the services provided by Calloc require access to other spaces. A residual issue 
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of accidental map access leading to accidental memory access by Calloc remains an unsolved problem that we 
discuss in more detail below. 

As a basis for providing services, Calloc recognizes a partitioning of every internal process into what we 
shall term the physician-patient pair. This recognition takes three forms: unlimited patience with "ill" 
(exception-causing) patients; support for physicians, limited to the kind of support best offered by a process 
running in system state such as Calloc; and a very contemporary intolerance for malpractice manifested as 
immediate and unreported termination of an erring physician along with its patient 

This scheme should work well provided only the most trusted software is used for implementing the 
physici<in half of each pair. The behavior of Calloc towards physicians and patients is the only mechanism 
depended on to encourage programmers to observe this discipline in writing process software. Without this 
discipline debugging should prove most difficult; conversely, with it the ease and efficiency of debugging 
should advance in step with advances in "medical technology.** 

To appreciate this design decision better it helps to think of physician software as requiring a level of 
dependability only a little less than that of Calloc itself The reason physicians are less critical is that the 
penalty for physician failure, vifhile seemingly very severe, is nevertheless less severe than the penalty for 
Calloc failure. A failed physician only leads to the unreported loss of a process, whereas Calloc failure can 
cause the unreported loss of the whole system. This also means that an inappropriate choice of physician will 
inconvenience only the chooser and not processes running in other spaces. 

There are of course alternative methods of debugging physicians that are not supported explicitly by 
Calloc, just as there are methods for debugging Calloc itself For the most part physicians themselves can be 
debugged by running them as patients. When running as physicians, an alternative mode of debugging is to 
put the physician in communication with another physician who can at least report the termination of its 

partner. ■ / - ■;' ■.■ ■>■■■ ■ ■■ ■ 

A different approach to the physician-patient relation is to make it hierarchical, putting physician 
debugging on the same level as' patient debugging. The cost is added complexity in Calloc in coping with 
such a hierarchy. Our preference here has been to sacrifice a certain amount of convenience in physician 
debugging in favor of keeping Calloc simple. 
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7.5.2. Machine Dependencies in Calloc 

The initial Calloc design is tailored to the SUN-1, a Motorola-68000-bascd CPU board. The only features 
of this board on which Calloc depends critically and which are not features of essentially every CPU board are 
the 68000's trace facility, without which the duties of physicians would require substantially more assistance 
from Calloc, compromising system robustness; and the SUN-l's pcr-pagc protection capability, on which 
Calloc depends to protect physicians from their patients and both from Calloc, and to make physicians 
invisible to their patients. To within these details, the principles of Calloc should be found to be broadly 
applicable. 

Ideally Calloc should be the junior sibling to Malloc, in that Calloc should have no say in how memory is 
allocated to processes and should not be able to interfere with Malloc's duties, in contrast to Malloc's absolute 
freedom. Unforturnately the SUN-1 does not support this level of protection since map access and hence 
unrestricted memory access is granted to all system state processes, not just to Malloc as we would prefer. 
Thus the promised protection of internal process memory from Calloc is only weakly achieved, by not having 
any Calloc code that intentionally references the map. Accidental map references remain an unfortunate 
possibility that we would hope fiiture hardware would make it easier to avoid. The absence of iterative 
constructs and address register arithmetic from the Calloc code should help to reduce die likelihood of such 
unintentional map accesses. One consolation is that at least Calloc is no worse in this respect than any other 
system-state schedulers. 

7.5.a. CaHoc Duties 

Calloc attends to the foilowing. 

1. Requests for animation (bringing to life) of a given process, that is, giving it a share of the cpu. 

2. Requests for sleep, thait is, temporary surrender of the q)u. 

3. Requests for termination, that is, permanent surrender of the cpu. 

4. Equitable allocation of the processor; at uniform intervals the active process is put to sleep and the 
next in turn is awoken (round-robin scheduling). 

5. Automatic saving and restoring of pc/sp/cc, the process's program counter, stack pointer, and 
condition codes. 

6. Error recovery. An erring process is permitted to try to recover on its own. No limit is placed on 
the number of errors made. Calloc depends critically on the physician-patient dichotomy to avoid 
the major problem associated with this degree of latitude, namely vegetating, the perpetual 

survival of terminally ill processes. 

7. Requests by a physician to run or single step its patient. The physician is at liberty to set 
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breakpoints in the patient, which Calloc supports in a way that makes this invisible to the patient 



7.5.4. Calioc Nonduties 

Many duties normally entrusted to system-state software are not attended to by Calloc, in the interests of 
autonomy, flexibility, and efficiency. Such duties often include the following. 

1. Saving and restoring the contents of the cpu other than pc/sp/cc. Calloc assumes that each 
internal process will save and restore the contents of the cpu registers that it cares about. 

2. Diagnosis, repair, or reporting of sick processes. The process must diagnose and report its own 
problems, using its physician component, and heal or terminate itself. 

3. Allocation of memory. This is handled at two levels on the SUN-1, as a consequence of details of 
its memory structure. At the higher level, SUN-1 memory is staictured into possibly overlapping 
spaces of varying sizes. Accordingly there exists Calloc's aforementioned companion Malloc, 
which like Calloc runs in system state at interrupt level 0. At a lower level is conventional 
memory allocation within a space, which is handled by the user processes themselves. 

4. Allocation of tlie processor to interrupt-driven processes (IDP's) (introduced at the start of the 
overview section). 

5. Creation and destmction of processes. Calloc draws a Pinnochio-like distinction between creation 
and animation, taking responsibility only for the latter. Process creation and destruction are left to 
user processes. The quality of the created process is up to the author of the creating process; in 
general the best effects should be obtained by creating processes with highly tnisted physicians. 
Process destruction entails primarily deallocation of resources, which though it may be handled by 
any component of the process, is for greatest reliability left to specialist programs running in user 
stale. -• ■ '■ ' --^r- 

6. Reading or writing of internal process memory. Calloc does not reference internal-process 
memory, making it independent of decisions about how system state processes access memory 
normally accessed in user state. Altliough the SUN-1 makes system-state access to user-state 
memory as easy as access to system-state memory, future boards may vary this. Calloc is immune 
to such variations. 

7. Capability management. No global system of capability management is envisaged for SUNOS. 
The definition and use of capabilities is intended to be a matter of agreement between consenting 
processes. The set of rights and duties of internal processes from Calloc's point of view provides 
an example of tliis. This philosophy is part of the overall decentralization philosophy of SUNOS. 

8. Interprocess communication. No global system of interprocess communication is envisaged for 
SUNOS. Instead it is expected that a variety of interprocess communication protocols will be 
used, one or two of which may come to dominate on account of tl?eir combination of general 
applicability and high efficiency. 

Calloc offers enough services to pcrniit quality care of the patient by its physician, including: 
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• Full access by the physician to the state of the patient. 

• Protection of the physician from the patient's illness; 

• Invisibility of the physician to the patient; 

• A single step facility to help the physician diagnose and/or treat the patient. 

Control is passed from the patient ("normal" status) to the physician ("suspended" status) when an error 
occurs.. ., ■ 

Physician access to the patient is straightforward for all of the patient except its pc/sp/cc, error state, and 
space size. To obtain this information a system call to Calloc is provided which returns this information in 
five CPU registers. This call also grants the physician read-write access to the patient's memory. 

Protection of the physician from the patient is implemented by allocating a portion of the space to the 
physician and denying write access to those pages while in normal status. A physician whose writable 
memory fits in one page (2K bytes) will require Calloc to access only one map entry for each change of status. 

Physician invisibility is achieved by denying the patient any read access to the space the physician writes in, 
the motivation being for the patient not to see mysterious variations in memory. Seeing or even executing the 
physician's code is permissible provided the code remains fixed. The physician should not use the patient*s 
stack in place of its own, except where it makes arrangements to completely erase all traces of its presence 
before returning to normal status. 



7.5.5. Requests to Sleep 

A process temporarily held up by lack of input or unavailability of some resource may temporarily 
surrender the CPU to Calloc. It does not get it back until all other processes have had a turn. This is 
synchronous sleep; as such it may not be necessary to save all the CPU registers. 

Where the cpu changes hands frequently (say every 100 microseconds or less), the affected processes will 
arrange to minimize context switching overhead, e.g. by replacing "while (Icondition) {pushstatc; sleep; 
popstate;}" with "if (Icondition) {pushstatc; do sleep while (Icondition); popstate;}" and treating functions 
containing "sleep" as though they declared all of d2-d7 and a2-a5 (a trivial mod to tlie compiler), saving any 
given register across the largest block containing the sleep but not containing a reference to that register. 
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7.5.6. Cleaning Up 

The following approach is proposed for having physicians clean up. There are three granularities of storage 
involved: space, stack, and frame. A space is defined by the 68000 board's SID (Space ID) register; spaces are 
protected from each other except when they overlap as when sharing for interprocess communication and 
related purposes. Stticks are associated with processes; each process has two stacks, one for normal use and a 
small one, normally inaccessible, for the physician. Frames are as defined by the C68 compiler (see section 
IS). . ■ ■ 

Per space: all storage is reclaimed by Malloc when a space is abandoned (contains no further viable 
pfoccsses)^ -'^ 

Per stack: Each space may contain any number of processes; these are freed by the process's physician 
when the process is terminated for any reason, as are other patient resources known to the physician such as 
stream pointers. 

Per frame: No fixed scheme is prescribed here; rather each exception handler is expected to understand its 
patient's conventions concerning stack use. A C68-dependent convention will be to use two sources of 
information: the add-to-stack-pointer instRiction produced by the C68 compiler after each call, and the link 
instruction at the entry to each function. Either of tliese uniquely determine the number of parameters, and 
togctlicr they provide a consistency check on each other in the event a6 or the stack has been badly damaged 
or a nonstandard calling sequence has been used without telling the exception handler. 

A significant advantage of this approach is that it does not commit itself unbendingly to a particular choice 
of calling sequence. New calling sequence conventions may require rewriting of physicians, but do not affect 
calloc itselfl ... 

7.5.7. The Cafloc Process Model 

Calloc has a conception of a process appropriate to Calloc's duties. Calloc divides its notion of the state of 
the process into data state and control state components. 

The data state components are: 

• a value for the SID (Space ID) register, determining which region of the memory map the process 
has access to; 

• pc/sp/cc values (program counter, stack pointer, condition code register) for each of the physician 
and the patient; 
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• the patient's error Status. 

The SID register value is determined by Malloc, who may also change it. Calloc uses it only to set the SID 
register for the current (mnning or retiring) process. Tlie SID register maps a virtual address to a map 
address, which further maps the result to a physical address. 

The pc/sp/cc values are used to initialize the cpu on exiting to the process. The patient error status is 
reported to the physician on request, along with the patient pc/sp/cc values. 

The control state components are: 

• activity: one of running, retiring, or sleeping; 

• status: normal or suspended. 

« A running process is one in control of the CPU. A retiring process is one which is attempting to go to sleep. 
A sleeping process is one that does not have control of the CPU. A running or retiring process is called 
current; there is at most one current process at a time. 

A normal process executes the patient when running, while a suspended process executes the physician. 
When retiring, a process executes the physician whether normal or suspended. 

The process state is represented in the present SUN implementation with the following 32-byte struct in 
the C programming language. 



pedef struct Procdesc 


/* 


process descriptor */ 


{int *patpc; 


/* 


pat program counter */ 


int *patsp; 


7* 


pat stack pointer ♦/ 


int *patsb; 


/* 


pat stack base */ 


int *phypc; 


/* 


phy program counter ♦/ 


int *physp; 


/* 


phy stack pointer */ 


int sid; 


/* 


space id */ 


char patcc; 


/* 


pat condition code reg */ 


char phycc; 


/* 


phy ditto */ 


short paterr; 


/* 


patient error status */ 


struct Procdesc ♦next; 


/* 


next process descriptor */ 



} *procdesc: 

The current process is identified with a variable Current of type procdesc. To facilitate removal of a 
terminated process the procdesc variable Last identifies the process that was current prior to the present one 
(with Last = Current if there is only one process). Last contains no information not dcducible less efficiently 
from Current. 
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7.5.8. Control State Transitions 

The behavior of Calloc towards the current process can be represented as a finite state automaton, the states 
being the control states of the process. This automaton has five inputs, namely error, terminate, sleep, run, 
and timeout. An error input may be an error exception, a trace exception, or a request to be considered to be 
in error. A terminate input is a request to be terminated. A sleep input is a request from the process to be put 
to sleep. A run input is a request from the physician to transfer process ownership to the padent, citJier for 
one step or indefinitely. A timeout input is a signal from the timer that this process's time is up. 



The following state transition table covers the case when exacdy one input has arrived. As we care only 
about the current process here, the initial states are normal running, suspended running, normal retiring, and 
suspended retiring. 



INPUT: error 



STATE: 
norm run. 

susp. run. 
norm ret. 
SUSP ret. 



I susp run 
j terminated 
I terminated 
1 terminated 



terminate 

terminated 
terminated 
terminated 
terminated 



sleep 

norm sleep 
susp sleep 
norm sleep 
susp sleep 



run 

susp run 

norm run 
terminated 
te rrainated 



timeout 

norm ret. 
susp ret, 
terminated 
terminated 



It is possible for any combination of (i) error, (ii) one of terminate, sleep, or run, and (iii) timeout to occur 
simultaneously. If error is present, then terminate, sleep, and run requests are ignored, thougji the request is 
stored as part of the error state of the patient. Otherwise multiple inputs are processed as though they had 
arrived sequentially in the order given in the table. Thus error and timeout togeUier take a running patient 
first to a running physician and then to a retiring physician. For the case of sleep witii timeout we add the 
condition that timeout of a sleeping process has no effect (Thus a returning patient that gets its sleep request 
in just as the timeout arrives survives by the skin of its teeth.) 



7.5.9. Calloc Services 

We now detail the services provided by Calloc. 

Animation The function animate(patpc,patsp,patsba,phypc ,physp,sid) requests 
Calloc to add to its list a process with the given pc/sp values for patient and physician and 
sb for patient,' a zero cc for each, a zero patient error status, and a control state of sleeping 
patient. 

Sleep The fimction sleep( ) requests Calloc to put the requesting process to sleep. When the 

process is reawoken later, its cpu registers d0-d7 and a0-a6 may have changed, but the 
pc/sp/cc values will be preserved. 

Termination The function tcrminatc() requests Calloc to tciminatc the requesting process. Calloc docs 
not consider the issue of returning the stack and streams to free storage. 
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Status 



Run 



Single Step 



The physician may use tlic function statusQ to extract from Calloc the entire state of the 
patient. This information is returned to the physician in registers d4 (pc), d5 (cc,crror 
status,space size), d6 (sp), and d7 (sb). In addition the physician is granted read and write 
access to tlie patient's space. This access is revoked on resumption of normal processing. 
Use of statusO by the patient counts as an error 

The physician may use the function run() to return the process from suspended to 
normal status. Calloc restores only the patient's pc/sp/cc; it is the physician's 
responsibility to restore the other registers. Calloc also restores the access control to this 
space in force at the time of animation of this process. 

The physician may use the fijnction single step() to achieve tlie same effect as runQ 
but in 6800Q trace state. The ensuing trace exception is treated by Calloc as an error of 
type trace and the process is then suspended again. 



7.6. The Edit-String Protocol 

Edit-strings are a particular representadon of strings designed to support a variety of protocols for 
operating on strings. The most general string editing operation, replacement, is supported, but certain 
special-purpose kinds of operations such as stream- read-and- write have particularly efficient implementations 
with edit-strmgs. All references to edit-strings are via ordinary pointers to individual data within a string. 



7.6.1 . The Edit-StrIng Data Structure 

Storage is divided into buffers each of size a power of two, each aligned by its size. Eacli buffer contains a 
header and a body. The header is structured into the following fields. 



typedef struct Bufhead 
{struct Buffer *next; 

struct Buffer *prev; 

char size; 

char type; 

short 11 im; 

short rlim; 

short refco; 
} •bufhead; 



/* 
/♦ 
/♦ 
/• 
/* 
/• 
/* 
/♦ 



Buffer head definition */ 

next buffer */ 

previous buffer, if any */ 

log base 2 of size of buffer */ 

type of data in buffer */ 

left end of data in buffer ♦/ 

right end of data in buffer */ 

number of owners of this buffer */ 



The exact start and end of data in the body are defined by both delimiters and the 1 1 im/rl im pair. The 
last delimiter before the start address marks die start boundary, while the first delimiter following the end 
address marks the end boundary. 



11 DECEMBER 1981 



66 



SUN USERS* GUIDE 



7.6.2. Reference 

All references to edit-strings are via pointers to data within tlie body of some buffer. Tliis differs from 
schemes where a reference is a more complex structure which may include a count of the remaining items in 
the current buffer and the address of a function to call when the count vanishes. 

Data are accessed via pointers in the usual way. In the case of accessing a stream the pointer will be 
incremented after the access. This may take it out of the data. The test for this is performed when accessing 
rather than when incrementing. The condition of being out of the data is recognized when the pointer points 
to a delimiter and the end address given in the buffer header does not lie beyond the pointer. When storing at 
the end of an edit-string, as when writing a stream, the writer only need update rlim if it writes a delimiter. 

7.6.3. Locating Blocik Headers 

The question arises as to how to locate the start of the buffer given only a pointer into the buffer body. To 

this end all buffers are taken to be of size a power of two, and are aligned on buffer boundaries, that is, they 

. - ■- • - ■ - ' ■■■■■■ 1. 

start at an address which is a multiple of their length. 

When the size of the buffer is known, the buffer header may be located by masking out the low-order bits 
of the pointer. In effect a pointer has two components, a pointer to the start of the buffer and an offset from 
that start. Unlike other ways of forming two-element structures, this approach has the benefit that the 
structure forms an ordinary machine address that can be used as an indirect reference and incremented in the 
usual ways. 

When the size of the buffer is not known, it may be determined by trying all sizes in decreasing order and 
for each, masking out the low-order bits of the pointer as in the case when the size is known. The largest size 
yielding a header which (a) is within the storage region allocated to this scheme and (b) contains this size in its 
size field, is the size of the containing buffer. The correctness of this method depends on the observations that 
(a) every address within a buffer yields the buffer header using SOME mask, and (b) every mask larger than 
must yield some buffer header. 

The advantage of this approach is that processes that know the buffer size in advance can run faster, while 
processes that don't, such as postmortem diagnosers, can still find their way around given only pointers into 
buffers. 
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7.6.4. Asynchronous Access 

The question now arises as to asynchronous reading and writing; can a reader get a consistent picture of a 
string while it is being written? In general a certain amount of explicit synchronization of independent 
processes may be needed for some kinds of reading and writing. However for some of the cases we are 
particularly concerned about, explicit synchronization can be avoided. 

Consider the case of any number of readers reading in either direction in a stream being written only at the 
ends (i.e. no inserting other than at tlie ends, and no deleting). By symmetry it suffices to consider a reader 
scanning forwards. A reader fetching a non-delimiter is assured that he is not at tlic end of the stream. 
Fetching a delimiter is more problematical; the delimiter may have been genuine at the time of the fetch, but 
may be replaced by some other datum by the writer before the reader fetches the end address. 

If the writer has not updated the end address then no serious problem arises; the reader merely has an out- 
of-date picture. However suppose that between the reader's reading the delimiter and checking the end 
address that the writer writes a non-delimiter and then the delimiter. The writer will Uien bring the end 
address up to date and the reader will be fooled into believing that the delimiter it read is a datimi. 

There is an easy cure for this problem. The reader identifying a delimiter as a datum should always refctch 
that datum and discard the old datum. The second fetch is guaranteed to be correct since all writing is 
performed at the end. This method avoids the expense of explicit synchronization. 

When the need does arise to synchronize explicitly, the question arises as to how to minimize overhead. 
System calls to raise interrupt priority or defeat the interrupt mechanisms are unduly expensive; it is 
considerably cheaper to rely on shared semaphores when these can be set, tested, and reset with single 
instructions. 
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